@obelyzk/sdk 1.1.0 → 1.3.0

package/README.md

@@ -1,505 +1,186 @@
 # @obelyzk/sdk
 
-Official TypeScript SDK for the **Obelysk Protocol** -- privacy-first DeFi on Starknet.
+TypeScript SDK for ObelyZK -- verifiable ML inference 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.
+Prove any supported model and get an on-chain verification receipt in a single call. All proofs use full OODS + Merkle + FRI + PoW (trustless) verification.
 
 ## Installation
 
 ```bash
-npm install @obelyzk/sdk starknet
+npm install @obelyzk/sdk
 ```
 
-`starknet` (v6+) is a required peer dependency. For React hooks, also ensure `react >= 18`.
-
-## Entry Points
-
-| 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 (Read-Only)
-
-No wallet or account needed for read-only queries:
-
-```typescript
-import { ObelyskClient } from '@obelyzk/sdk/obelysk';
-
-const obelysk = new ObelyskClient({
-  network: 'mainnet',
-  rpcUrl: 'https://your-rpc.com',
-});
-
-// Query DarkPool epoch
-const epoch = await obelysk.darkPool.getEpochInfo();
-console.log('Epoch:', epoch.epoch, 'Phase:', epoch.phase);
-
-// 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);
-
-// Query OTC orderbook depth
-const depth = await obelysk.otc.getOrderbookDepth(0);
-console.log('Bids:', depth.bids.length, 'Asks:', depth.asks.length);
-```
-
----
-
-## ObelyskClient Configuration
+## Quick Start
 
 ```typescript
-import { ObelyskClient } from '@obelyzk/sdk/obelysk';
-import { Account, RpcProvider } from 'starknet';
-
-const provider = new RpcProvider({ nodeUrl: 'https://your-rpc.com' });
-const account = new Account(provider, '0xADDRESS', '0xPRIVATE_KEY');
+import { createProverClient } from "@obelyzk/sdk";
 
-const obelysk = new ObelyskClient({
-  // Required
-  network: 'mainnet', // 'mainnet' | 'sepolia'
+const client = createProverClient();
 
-  // Recommended
-  rpcUrl: 'https://your-rpc.com', // default public RPCs have rate limits
-
-  // Required for write operations
-  account, // starknet.js Account
-
-  // Optional: VM31 relayer (for UTXO vault operations)
-  relayerUrl: 'https://relay.bitsage.network:3080',
-  relayerApiKey: 'your-api-key',
-
-  // Optional: ElGamal private key (hex). If omitted, generated fresh.
-  privacyPrivateKey: '0x...',
+// Prove a model and verify on-chain
+const result = await client.prove({
+  model: "smollm2-135m",
+  input: [1.0, 2.0, 3.0],
+  onChain: true,
 });
-```
-
-All 14 mainnet contract addresses are baked into the SDK. No manual address configuration is needed.
 
----
-
-## Sub-Clients
+console.log("Output:", result.output);
+console.log("Proof hash:", result.proofHash);
+console.log("TX hash:", result.txHash);
+console.log("Verified:", result.verified);
+```
 
-The `ObelyskClient` exposes 10 sub-clients, each handling a specific protocol domain.
+## API Reference
 
-### 1. Privacy Pool (`obelysk.privacyPool`)
+### `createProverClient(options?)`
 
-Deposit tokens into shielded pools using Pedersen commitments. Withdraw with nullifier + Merkle proof to break the on-chain link between depositor and recipient.
+Create a prover client instance.
 
 ```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,
+const client = createProverClient({
+  url: "https://api.obelysk.com",  // default; or your own GPU prover
+  apiKey: "your-api-key",           // optional, for rate limiting
+  timeout: 300_000,                 // request timeout in ms (default: 5 min)
 });
-
-// Read-only queries
-const root = await obelysk.privacyPool.getMerkleRoot('eth');
-const stats = await obelysk.privacyPool.getPoolStats('eth');
 ```
 
-### 2. DarkPool (`obelysk.darkPool`)
+### `client.prove(request)`
 
-Commit-reveal batch auction trading. Orders are committed as hashes during the commit phase, revealed during the reveal phase, and matched during settlement.
+Prove an ML model execution and optionally verify on-chain.
 
 ```typescript
-// 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',
+const result = await client.prove({
+  model: "smollm2-135m",        // model name or HuggingFace ID
+  input: [1.0, 2.0, 3.0],      // input tensor (flat array)
+  onChain: true,                 // submit to Starknet (default: false)
+  recursive: true,               // use recursive STARK (default: true)
+  network: "sepolia",            // Starknet network (default: "sepolia")
 });
-// Save `orderData` -- needed for reveal
-
-// 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();
+// result: {
+//   output: number[],           // model output tensor
+//   proofHash: string,          // Poseidon hash of the proof
+//   txHash?: string,            // Starknet TX hash (if onChain: true)
+//   verified?: boolean,         // on-chain verification status
+//   proveTime: number,          // proving time in seconds (~102s for SmolLM2)
+//   recursiveTime: number,      // recursive STARK time (~3.55s)
+//   felts: number,              // calldata size in felts (~942)
+//   modelId: string,            // hex model identifier
+// }
 ```
 
-### 3. Stealth Payments (`obelysk.stealth`)
+### `client.attest(request)`
 
-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.
+Prove and submit a full attestation with streaming verification.
 
 ```typescript
-// Send 1000 SAGE to a stealth address
-const { txHash, announcement } = await obelysk.stealth.send({
-  to: '0xReceiverAddress...',
-  token: 'sage',
-  amount: '1000',
+const attestation = await client.attest({
+  model: "smollm2-135m",
+  input: [1.0, 2.0, 3.0],
+  submitOnChain: true,
 });
-
-// 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...' });
 ```
 
-### 4. Confidential Transfer (`obelysk.confidentialTransfer`)
+### `client.getModels()`
 
-Peer-to-peer transfers where the amount is encrypted on-chain using ElGamal. Only sender and recipient can see the value.
+List all available models on the prover.
 
 ```typescript
-// 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',
-});
-
-// Query encrypted balance
-const encBalance = await obelysk.confidentialTransfer.getEncryptedBalance('0xAddress...');
-
-// Decrypt locally (requires private key)
-const balance = obelysk.privacy.decrypt(encBalance, privateKey);
+const models = await client.getModels();
+// [{ name: "smollm2-135m", params: "135M", layers: 30, ... }, ...]
 ```
 
-### 5. Prover Staking (`obelysk.staking`)
+### `client.getJob(jobId)`
 
-Stake SAGE tokens to participate as a GPU prover in the network. Four tiers: Consumer, Professional, DataCenter, H100.
+Check the status of an async proving job.
 
 ```typescript
-// Stake 50,000 SAGE as a DataCenter prover
-await obelysk.staking.stake({ amount: '50000', gpuTier: 'DataCenter' });
-
-// 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();
+const job = await client.getJob("job-abc123");
+// { status: "completed", progress: 100, result: { ... } }
 ```
 
-### 6. Privacy Router (`obelysk.router`)
+## Async Jobs
 
-Read-only views into the Privacy Router contract -- private account registration, encrypted balances, nullifier tracking, and audit support.
+For large models, proving runs asynchronously:
 
 ```typescript
-const account = await obelysk.router.getAccount('0xAddress...');
-if (account?.registered) {
-  console.log('Public key:', account.publicKey);
-  console.log('Encrypted balance:', account.encryptedBalance);
-}
-
-const spent = await obelysk.router.isNullifierUsed('0xNullifier...');
-```
-
-### 7. Shielded Swap (`obelysk.swap`)
+const { jobId } = await client.prove({
+  model: "phi-3-mini",
+  input: data,
+  async: true,
+});
 
-Privacy-preserving AMM swaps routed through Ekubo. Swaps consume a privacy pool withdrawal proof and produce a new shielded commitment.
+// Poll for completion
+let job;
+do {
+  await new Promise(r => setTimeout(r, 5000));
+  job = await client.getJob(jobId);
+  console.log(`Progress: ${job.progress}%`);
+} while (job.status === "running");
 
-```typescript
-// Query swap router state
-const swapCount = await obelysk.swap.getSwapCount();
-const pool = await obelysk.swap.getPool(tokenAddress);
-const fee = await obelysk.swap.getFee();
+console.log("Result:", job.result);
 ```
 
-### 8. VM31 UTXO Vault (`obelysk.vm31`)
+## Supported Models
 
-UTXO-based privacy vault using Poseidon2-M31 hashing. Transactions are submitted to the VM31 relayer, which batches and proves them on-chain.
+| Model | Params | Prove Time (GPU) | Recursive Felts |
+|-------|--------|-------------------|-----------------|
+| SmolLM2-135M | 135M | ~102s | 942 |
+| Qwen2-0.5B | 500M | ~45s | ~900 |
+| Phi-3-mini | 3.8B | ~180s | ~950 |
 
-```typescript
-// 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 */],
-});
+## On-Chain Verification
 
-// Check batch status
-const batch = await obelysk.vm31.getBatchStatus(result.batchId);
-
-// Query on-chain state
-const root = await obelysk.vm31.getMerkleRoot();
-const noteCount = await obelysk.vm31.getNoteCount();
-const relayer = await obelysk.vm31.getRelayerInfo();
-```
+When `onChain: true`, the SDK submits the proof to the ObelyZK Recursive Verifier contract on Starknet Sepolia. Verification uses full OODS + Merkle + FRI + PoW (trustless).
 
-### 9. VM31 Bridge (`obelysk.bridge`)
+- **Contract:** `0x707819dea6210ab58b358151419a604ffdb16809b568bf6f8933067c2a28715`
+- **Method:** `verify_recursive(model_id, io_commitment, stark_proof_data)`
+- **Verification:** Full OODS + Merkle + FRI + PoW (trustless)
+- **Felts:** ~942 per proof (49x compression)
+- **Cost:** ~$0.02 per verification on Sepolia
 
-Bridge between the VM31 UTXO pool and ElGamal-based ConfidentialTransfer system.
+You can verify independently:
 
 ```typescript
-const config = await obelysk.bridge.getConfig();
-const assetPair = await obelysk.bridge.getAssetPair(0); // wBTC mapping
-const relayer = await obelysk.bridge.getRelayer();
-```
-
-### 10. OTC Orderbook (`obelysk.otc`)
-
-On-chain limit and market order book for peer-to-peer token trading.
+import { RpcProvider } from "starknet";
 
-```typescript
-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,
+const provider = new RpcProvider({
+  nodeUrl: "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_8/demo",
 });
 
-// Place a market order
-await obelysk.otc.placeMarketOrder({
-  pairId: 0,
-  side: OrderSide.Sell,
-  amount: 1000_000_000_000_000_000_000n,
+const result = await provider.callContract({
+  contractAddress: "0x707819dea6210ab58b358151419a604ffdb16809b568bf6f8933067c2a28715",
+  entrypoint: "get_recursive_verification_count",
+  calldata: [modelId],
 });
 
-// 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);
-
-// Cancel
-await obelysk.otc.cancelOrder(orderId);
+console.log("Verification count:", result[0]);
 ```
 
----
-
-## ElGamal Privacy Primitives
-
-Available from both `@obelyzk/sdk/privacy` and `@obelyzk/sdk/obelysk`.
-
-```typescript
-import { ObelyskPrivacy } from '@obelyzk/sdk/privacy';
-
-const privacy = new ObelyskPrivacy();
-
-// Generate a key pair
-const keyPair = privacy.generateKeyPair();
-console.log('Public key:', keyPair.publicKey); // ECPoint { x, y }
+## Environment Variables
 
-// Encrypt an amount (only the private key holder can decrypt)
-const ciphertext = privacy.encrypt(1_000_000n, keyPair.publicKey);
-// ciphertext = { c1: ECPoint, c2: ECPoint }
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `OBELYSK_API_KEY` | API key for hosted prover | For hosted |
+| `OBELYSK_PROVER_URL` | Custom prover URL | For self-hosted |
+| `STARKNET_ACCOUNT` | Starknet account address | For on-chain |
+| `STARKNET_PRIVATE_KEY` | Starknet private key | For on-chain |
 
-// Decrypt
-const amount = privacy.decrypt(ciphertext, keyPair.privateKey);
-console.log(amount); // 1000000n
+## Self-Hosted Prover
 
-// 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);
-```
-
-### Low-Level Crypto Functions
-
-```typescript
-import {
-  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));
-```
-
----
-
-## 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`).
+Point the SDK at your own GPU prover instead of the hosted service:
 
 ```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),
+const client = createProverClient({
+  url: "http://your-gpu-server:8080",
 });
 ```
 
-Requires Web Crypto API (Node 20+ or any modern browser).
-
----
-
-## Denomination Validation
-
-Privacy pool and VM31 vault deposits must use standard denominations to prevent exact-amount correlation attacks. The SDK enforces this client-side.
-
-```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
-
-// List valid denominations for an asset
-const denoms = getDenominations('usdc');
-// [1 USDC, 5 USDC, 10 USDC, 50 USDC, 100 USDC, 500 USDC]
-```
-
-Supported tokens: wBTC, SAGE, ETH, STRK, USDC. Unknown assets pass through without restriction.
-
----
-
-## Contract Addresses
-
-All mainnet and Sepolia addresses are available programmatically:
-
-```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"
-```
-
-### 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` |
-
----
-
-## React Hooks
-
-```typescript
-import { useBitSage, usePrivacy, useStwoProver } from '@obelyzk/sdk/react';
-
-function App() {
-  const { client, isConnected } = useBitSage();
-  const { privacy, keyPair, generateKeyPair } = usePrivacy();
-  const { prover, submitJob, status } = useStwoProver();
-
-  return (
-    <div>
-      <p>Connected: {String(isConnected)}</p>
-      <button onClick={generateKeyPair}>Generate Keys</button>
-    </div>
-  );
-}
-```
-
-Requires `react >= 18` as a peer dependency (optional -- only needed if you use this entry point).
-
----
-
-## Requirements
-
-- Node.js >= 18
-- `starknet` >= 6.0.0
-- TypeScript >= 5.0 (recommended)
-
----
+See the [Self-Hosting Guide](../../libs/stwo-ml/scripts/pipeline/GETTING_STARTED.md#option-3-self-host-a-gpu-prover) for setup instructions.
 
-## License
+## Links
 
-MIT
+- [GitHub](https://github.com/obelyzk/stwo-ml)
+- [npm](https://www.npmjs.com/package/@obelyzk/sdk)
+- [Getting Started](../../libs/stwo-ml/scripts/pipeline/GETTING_STARTED.md)
+- [On-Chain Docs](../../libs/stwo-ml/docs/ON_CHAIN_VERIFICATION.md)