diff --git a/CLAUDE.md b/CLAUDE.md index a7fc438..15a7613 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ **Live URL:** https://sipher.sip-protocol.org **Tagline:** "Privacy-as-a-Skill for Multi-Chain Agents" **Purpose:** REST API + OpenClaw skill enabling any autonomous agent to add transaction privacy via SIP Protocol -**Stats:** 71 endpoints | 573 tests | 17 chains | 4 client SDKs (TS, Python, Rust, Go) | Eliza plugin +**Stats:** 58 REST endpoints | 497 REST tests (32 suites) + 23 agent tests | 21 agent tools | 9 HERALD X tools | 17 chains | 4 client SDKs (TS, Python, Rust, Go) | Eliza plugin --- @@ -48,13 +48,13 @@ - **Runtime:** Node.js 22 (LTS) - **Framework:** Express 5 - **Language:** TypeScript (strict) -- **Core:** @sip-protocol/sdk v0.7.4 (stealth addresses, commitments, encryption, multi-chain) +- **Core:** @sip-protocol/sdk v0.7.4 (stealth addresses, commitments, XChaCha20-Poly1305 encryption, multi-chain) - **Solana:** @solana/web3.js v1 (transactions, RPC) - **Validation:** Zod v3 - **Logging:** Pino v9 (structured JSON, audit logs) - **Docs:** swagger-ui-express (OpenAPI 3.1) - **Cache:** Redis 7 (rate limiting, idempotency) with in-memory fallback -- **Testing:** Vitest + Supertest (465 tests) +- **Testing:** Vitest + Supertest (497 REST + 23 agent tests) - **Deployment:** Docker + GHCR → VPS (port 5006) - **Domain:** sipher.sip-protocol.org @@ -67,7 +67,7 @@ pnpm install # Install dependencies pnpm dev # Dev server (localhost:5006) pnpm build # Build for production -pnpm test -- --run # Run tests (573 tests, 36 suites) +pnpm test -- --run # Run REST tests (497 tests, 32 suites) pnpm typecheck # Type check pnpm demo # Full-flow demo (requires dev server running) pnpm openapi:export # Export static OpenAPI spec to dist/openapi.json @@ -192,11 +192,8 @@ sipher/ │ │ ├── viewing-key.ts # generate, derive, verify-hierarchy, disclose, decrypt │ │ ├── privacy.ts # score (surveillance/privacy analysis) │ │ ├── rpc.ts # GET /v1/rpc/providers (provider info) -│ │ ├── range-proof.ts # STARK range proofs (generate, verify) │ │ ├── backends.ts # Privacy backend registry (list, health, select) -│ │ ├── arcium.ts # Arcium MPC (compute, status, decrypt) -│ │ ├── inco.ts # Inco FHE (encrypt, compute, decrypt) -│ │ ├── private-swap.ts # Private swap (Jupiter DEX + stealth) +│ │ ├── private-swap.ts # Private swap (real Jupiter DEX + stealth) │ │ ├── session.ts # Session CRUD (create, get, update, delete) │ │ ├── governance.ts # Governance voting privacy (encrypt, submit, tally, getTally) │ │ ├── compliance.ts # Compliance (disclose, report, report/:id) @@ -208,13 +205,8 @@ sipher/ │ │ ├── rpc-provider.ts # Provider factory (helius, quicknode, triton, generic) │ │ ├── transaction-builder.ts # Unsigned tx serialization (Solana) │ │ ├── chain-transfer-builder.ts # Chain-agnostic transfer dispatch (Solana/EVM/NEAR) -│ │ ├── stark-provider.ts # STARK range proof provider (M31 limbs, mock prover) -│ │ ├── arcium-provider.ts # Arcium MPC mock provider (state machine, LRU cache) -│ │ ├── arcium-backend.ts # Arcium PrivacyBackend implementation (compute type) -│ │ ├── inco-provider.ts # Inco FHE mock provider (encryption, computation, noise budget) -│ │ ├── inco-backend.ts # Inco PrivacyBackend implementation (compute type) │ │ ├── helius-provider.ts # Helius DAS API client (getAssetsByOwner, fallback) -│ │ ├── jupiter-provider.ts # Jupiter DEX mock provider (quotes, swap transactions) +│ │ ├── jupiter-provider.ts # Jupiter DEX provider (real lite-api.jup.ag quotes + swaps) │ │ ├── private-swap-builder.ts # Private swap orchestrator (stealth + C-SPL + Jupiter) │ │ ├── backend-comparison.ts # Backend comparison service (scoring, caching, recommendations) │ │ ├── session-provider.ts # Session management (LRU cache + Redis, CRUD, ownership) @@ -223,7 +215,7 @@ sipher/ │ │ ├── jito-provider.ts # Jito block engine (real via JITO_BLOCK_ENGINE_URL, mock fallback) │ │ ├── stripe-provider.ts # Mock Stripe provider (subscriptions, invoices, portal, webhooks) │ │ ├── usage-provider.ts # Usage tracking & daily quotas (Redis + LRU fallback) -│ │ └── backend-registry.ts # Privacy backend registry singleton (SIPNative + Arcium + Inco) +│ │ └── backend-registry.ts # Privacy backend registry singleton (SIPNative) │ └── types/ │ └── api.ts # ApiResponse, HealthResponse ├── skill.md # OpenClaw skill file (GET /skill.md) diff --git a/README.md b/README.md index 81e7af3..c22247c 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,8 @@ hidden amounts, and compliance viewing keys across 17 chains.** *Stealth addresses • Pedersen commitments • Viewing key hierarchies • On-chain Anchor program • 4 client SDKs* -[![Tests](https://img.shields.io/badge/tests-573%20passing-brightgreen)]() -[![Endpoints](https://img.shields.io/badge/endpoints-71-blue)]() +[![Tests](https://img.shields.io/badge/tests-497%20passing-brightgreen)]() +[![Endpoints](https://img.shields.io/badge/endpoints-58-blue)]() [![Chains](https://img.shields.io/badge/chains-17-purple)]() [![SDKs](https://img.shields.io/badge/SDKs-4-orange)]() [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)]() @@ -55,12 +55,12 @@ https://github.com/user-attachments/assets/a4a87b0c-7168-4677-b8e6-457debb98cb0 - [What's Real vs. What's Preview](#-whats-real-vs-whats-preview) - [Quick Start](#-quick-start) - [SDK Depth](#-sdk-depth-sip-protocolsdk-v074) -- [API Endpoints](#-api-endpoints-70-total) +- [API Endpoints](#-api-endpoints-58-total) - [Multi-Chain Support](#-multi-chain-support-17-chains) - [Agent Workflow](#-agent-workflow) - [Architecture](#%EF%B8%8F-architecture) - [Client SDKs](#-client-sdks) -- [Test Suite](#-test-suite-554-tests-35-suites) +- [Test Suite](#-test-suite-497-tests-32-suites) - [Tech Stack](#%EF%B8%8F-tech-stack) - [Deployment](#-deployment) - [Decentralization Roadmap](#%EF%B8%8F-decentralization-roadmap) @@ -127,7 +127,7 @@ Agent (Claude, LangChain, CrewAI, OpenClaw, etc.) ▼ REST API (any language, any framework) ┌──────────────────────────────────────────────────────────────────┐ │ Sipher API │ -│ Express 5 + TypeScript │ 71 endpoints │ Tiered rate limiting │ +│ Express 5 + TypeScript │ 58 endpoints │ Tiered rate limiting │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Auth │ │ Rate │ │ Idempot- │ │ Audit │ │ @@ -147,8 +147,7 @@ Agent (Claude, LangChain, CrewAI, OpenClaw, etc.) │ • Pedersen │ │ Config PDA: │ │ • XChaCha20 │ │ BVawZk...WZwZ │ │ • BIP32 keys │ │ │ -│ • Anchor txs │ │ ZK Verifier: │ -│ • Range proofs │ │ Sunspot (roadmap) │ +│ • Anchor txs │ │ │ │ • 17 chains │ │ │ └──────────────────┘ └───────────────────────┘ ``` @@ -236,7 +235,6 @@ curl https://sipher.sip-protocol.org/v1/demo | jq '.data.summary' "Pedersen commitments (homomorphic)", "XChaCha20-Poly1305 (viewing key encryption)", "BIP32 hierarchical key derivation", - "STARK range proofs (M31 limbs)", "Keccak256 nullifier derivation (governance)" ] } @@ -313,7 +311,6 @@ Every crypto operation uses audited, production-grade libraries: | **SHA-256** | `@noble/hashes` | Key hashing, view tags | | **Keccak-256** | `@noble/hashes` | Nullifier derivation (governance) | | **BIP32/BIP39** | `@scure/bip32` | Hierarchical viewing key derivation | -| **STARK Range Proofs** | Custom (M31 field) | Prove value >= threshold without revealing value | All `@noble/*` and `@scure/*` libraries are by [Paul Miller](https://paulmillr.com/) — independently audited, zero-dependency, used by MetaMask, Ethereum Foundation, and the broader Web3 ecosystem. @@ -328,9 +325,7 @@ All `@noble/*` and `@scure/*` libraries are by [Paul Miller](https://paulmillr.c - **Shielded Transfers** — unsigned transaction building for Solana (SOL + SPL tokens) - **Chain-Agnostic Private Transfer** — Solana, EVM (5 chains), and NEAR in one endpoint - **Privacy Scoring** — 0-100 wallet analysis with factor breakdown and recommendations -- **STARK Range Proofs** — prove value >= threshold without revealing the value - **Governance Voting** — encrypted ballots with homomorphic tally and nullifier-based double-vote prevention -- **Backend Comparison Engine** — SIPNative, Arcium MPC, Inco FHE with scoring and recommendations - **Session Management** — persistent defaults per agent (chain, privacy level, backend) - **Daily Quotas + Tiered Rate Limiting** — free (100/hr), pro (10K/hr), enterprise (100K/hr) - **4 Auto-Generated Client SDKs** — TypeScript, Python, Rust, Go @@ -345,7 +340,7 @@ Sipher isn't a human tool with an API bolted on. Every design decision prioritiz | Pillar | How Sipher Delivers | |--------|-------------------| -| **Discovery** | [`/skill.md`](https://sipher.sip-protocol.org/skill.md) — OpenClaw-compatible skill file. Agents discover, parse, and use all 71 endpoints without human configuration. Self-describing API at `/`, error catalog at `/v1/errors`, full schema at `/v1/openapi.json`. | +| **Discovery** | [`/skill.md`](https://sipher.sip-protocol.org/skill.md) — OpenClaw-compatible skill file. Agents discover, parse, and use all 58 endpoints without human configuration. Self-describing API at `/`, error catalog at `/v1/errors`, full schema at `/v1/openapi.json`. | | **Integration** | Pure REST + JSON. No browser, no OAuth, no cookies. 4 auto-generated SDKs (TypeScript, Python, Rust, Go). API key auth via `X-API-Key` header — the simplest auth pattern for agents. | | **Autonomy** | [`privacy-demo-agent.ts`](scripts/privacy-demo-agent.ts) runs 20 steps across 34 endpoints with zero human intervention. Sessions (`X-Session-Id`) maintain state across multi-step workflows. No CAPTCHA, no manual verification. | | **Reliability** | 11+ mutation endpoints support `Idempotency-Key` for safe retries. Structured error responses with machine-readable codes and retry guidance. Agents can reason about failures, not parse HTML error pages. | @@ -404,9 +399,8 @@ Core endpoint latency (localhost, Node.js 22, Apple M-series): | `/v1/viewing-key/generate` | 2ms | 4ms | 5ms | | `/v1/scan/payments` | 5ms | 9ms | 12ms | | `/v1/privacy/score` | 2ms | 4ms | 6ms | -| `/v1/proofs/range/generate` | 3ms | 6ms | 8ms | -All operations use real cryptographic primitives (Ed25519 ECDH, Pedersen commitments, XChaCha20-Poly1305, STARK proofs). Benchmark your own: `npx tsx scripts/benchmark.ts` +All operations use real cryptographic primitives (Ed25519 ECDH, Pedersen commitments, XChaCha20-Poly1305). Benchmark your own: `npx tsx scripts/benchmark.ts` --- diff --git a/skill.md b/skill.md index 02df11f..7388395 100644 --- a/skill.md +++ b/skill.md @@ -504,227 +504,9 @@ Supported tokens: `C-wSOL`, `C-USDC`, `C-USDT`. All C-SPL endpoints support `Ide --- -### STARK Range Proofs (Preview — mock prover) +### Private Swap -Prove that a hidden value in a Pedersen commitment meets a threshold — without revealing the value. Uses M31 limb decomposition (Mersenne prime 2^31-1). Currently uses a mock STARK prover; real Murkl WASM integration coming soon. - -#### Generate Range Proof - -``` -POST /v1/proofs/range/generate -Content-Type: application/json - -{ - "value": "1000000000", - "threshold": "500000000", - "blindingFactor": "0x...", - "commitment": "0x..." -} -``` - -**Parameters:** -- `value` — The secret value to prove (not revealed in the proof) -- `threshold` — Minimum value (public, included in proof) -- `blindingFactor` — 32-byte hex blinding factor for commitment -- `commitment` — Optional existing Pedersen commitment. If omitted, auto-created from value + blindingFactor. - -Returns: `proof` (type, proof hex, publicInputs), `commitment`, `metadata` (prover, decomposition, limbCount, security). - -Supports `Idempotency-Key` header. - -#### Verify Range Proof - -``` -POST /v1/proofs/range/verify -Content-Type: application/json - -{ - "type": "range", - "proof": "0x...", - "publicInputs": ["0x...", "0x..."] -} -``` - -Returns: `{ valid: boolean }` - ---- - -### Privacy Backends - -List, inspect, and select privacy backends. Each backend implements a different privacy strategy (stealth addresses, FHE, MPC). - -#### List All Backends - -``` -GET /v1/backends -``` - -Returns: `backends[]` (name, type, chains, enabled, priority, capabilities, health), `total`, `totalEnabled`. - -#### Check Backend Health - -``` -GET /v1/backends/:id/health -``` - -Probes a specific backend. Returns: `available`, `estimatedCost`, `estimatedTime`, `health` (circuit breaker state), `metrics` (request counts, latency), `capabilities`. - -#### Select Preferred Backend - -``` -POST /v1/backends/select -Content-Type: application/json - -{ "backend": "sip-native" } -``` - -Sets the preferred privacy backend for your API key. Requires a tiered API key (Free/Pro/Enterprise). Returns: `keyId`, `preferredBackend`. - -#### Compare Backends - -``` -POST /v1/backends/compare -Content-Type: application/json - -{ - "operation": "stealth_privacy", - "chain": "solana", - "prioritize": "cost" -} -``` - -**Parameters:** -- `operation` — `stealth_privacy`, `encrypted_compute`, or `compliance_audit` -- `chain` — Target blockchain (default: `solana`) -- `amount` — Optional transaction amount in smallest units -- `prioritize` — Optional: `cost`, `speed`, or `privacy` (adjusts scoring weights to 60%) - -Returns: `comparisons[]` (backend, type, available, costLamports, costSOL, latencyMs, latencyCategory, privacyLevel, capabilities, score 0-100, recommended), `recommendation` (best_overall, best_value, fastest, most_private, reasoning). - -Scoring: cost 40%, latency 30%, privacy 30% (default). Use `prioritize` to shift weights. - ---- - -### Arcium MPC Compute (Preview — mock backend) - -Submit encrypted computations to the Arcium MPC cluster. Status progresses: submitted → encrypting → processing → finalizing → completed. - -#### Submit Computation - -``` -POST /v1/arcium/compute -Content-Type: application/json - -{ - "circuitId": "private_transfer", - "encryptedInputs": ["0xdeadbeef", "0xcafebabe"], - "chain": "solana", - "cipher": "aes256" -} -``` - -**Parameters:** -- `circuitId` — Circuit: `private_transfer` (2 inputs), `check_balance` (1 input), `validate_swap` (3 inputs) -- `encryptedInputs` — Hex-encoded encrypted inputs (1-10) -- `chain` — Target chain (default: `solana`) -- `cipher` — Encryption cipher: `aes128`, `aes192`, `aes256`, `rescue` (default: `aes256`) - -Returns: `computationId` (arc_...), `status`, `estimatedCompletion`, `supportedCircuits`. - -Supports `Idempotency-Key` header. - -#### Poll Status - -``` -GET /v1/arcium/compute/:id/status -``` - -Returns: `computationId`, `status`, `progress` (0-100), `output` (only when completed), `proof` (only when completed). - -#### Decrypt Result - -``` -POST /v1/arcium/decrypt -Content-Type: application/json - -{ - "computationId": "arc_...", - "viewingKey": { - "key": "0x...", - "path": "m/44/501/0", - "hash": "0x..." - } -} -``` - -Returns: `decryptedOutput`, `verificationHash`, `circuitId`. - ---- - -### Inco FHE Compute (Preview — mock backend) - -Encrypt values, compute on ciphertexts homomorphically, and decrypt results using Fully Homomorphic Encryption. FHE operations complete synchronously (no status polling needed). Tracks noise budget consumption per operation. - -#### Encrypt Value - -``` -POST /v1/inco/encrypt -Content-Type: application/json - -{ - "plaintext": 42, - "scheme": "tfhe", - "label": "my-value" -} -``` - -**Parameters:** -- `plaintext` — Value to encrypt (number or string) -- `scheme` — FHE scheme: `fhew` (fast boolean ops) or `tfhe` (general-purpose) -- `label` — Optional label - -Returns: `encryptionId` (inc_...), `ciphertext`, `scheme`, `noiseBudget` (100), `supportedSchemes`. - -#### Compute on Ciphertexts - -``` -POST /v1/inco/compute -Content-Type: application/json - -{ - "operation": "add", - "ciphertexts": ["0x...", "0x..."], - "scheme": "tfhe" -} -``` - -**Parameters:** -- `operation` — `add` (2 ops, noise: 5), `mul` (2 ops, noise: 15), `not` (1 op, noise: 3), `compare_eq` (2 ops, noise: 8), `compare_lt` (2 ops, noise: 8) -- `ciphertexts` — Hex-encoded ciphertexts (1-3) -- `scheme` — FHE scheme (default: `tfhe`) - -Returns: `computationId` (inc_...), `operation`, `resultCiphertext`, `noiseBudgetRemaining`, `status: "completed"`. - -Supports `Idempotency-Key` header. - -#### Decrypt Result - -``` -POST /v1/inco/decrypt -Content-Type: application/json - -{ - "computationId": "inc_..." -} -``` - -Returns: `decryptedOutput`, `verificationHash`, `operation`. - ---- - -### Private Swap (Preview — mock backend) - -Privacy-preserving token swap via Jupiter DEX. Orchestrates stealth address generation, optional C-SPL wrapping, and Jupiter swap into a single call. Output routed to a stealth address with Pedersen commitment. +Privacy-preserving token swap via real Jupiter API. Orchestrates stealth address generation, optional C-SPL wrapping, and Jupiter swap into a single call. Output routed to a stealth address with Pedersen commitment. ``` POST /v1/swap/private @@ -832,7 +614,7 @@ Returns: cached tally result (same shape as tally response). Tallies expire afte --- -### Jito Gas Abstraction (Preview — mock backend) +### Jito Gas Abstraction Submit transactions via Jito bundles for MEV protection. Requires pro or enterprise tier. @@ -995,7 +777,7 @@ Content-Type: application/json - `defaults.chain` — Default chain for stealth operations (17 chains supported) - `defaults.privacyLevel` — `standard`, `shielded`, or `maximum` - `defaults.rpcProvider` — `helius`, `quicknode`, `triton`, or `generic` -- `defaults.backend` — `sip-native`, `arcium`, or `inco` +- `defaults.backend` — `sip-native` - `defaults.defaultViewingKey` — 0x-prefixed hex viewing key - `ttlSeconds` — Session TTL (min: 60, default: 3600, max: 86400) @@ -1115,7 +897,7 @@ GET /v1/demo → JSON with 25 steps, 35+ endpoints exercised, real crypto GET /demo → Markdown-formatted summary (agent-readable) ``` -Returns stealth address generation (multi-chain), Pedersen commitments (homomorphic math), viewing key hierarchy (BIP32), STARK range proofs, governance voting, and more — all running live. +Returns stealth address generation (multi-chain), Pedersen commitments (homomorphic math), viewing key hierarchy (BIP32), governance voting, and more — all running live. --- @@ -1137,7 +919,6 @@ Returns stealth address generation (multi-chain), Pedersen commitments (homomorp | Module | Description | Status | |--------|-------------|--------| | anchor-transfer | On-chain shielded transfers via Anchor program | Production | -| sunspot-verifier | Noir → Groth16 ZK proof verification (3 proof types) | Roadmap | | privacy-adapter | Unified orchestrator (transfer, scan, claim) | Production | | stealth-scanner | Real-time + historical payment detection | Production | | providers/helius | Helius DAS API (asset queries, metadata) | Production | @@ -1156,7 +937,6 @@ Returns stealth address generation (multi-chain), Pedersen commitments (homomorp | XChaCha20-Poly1305 | @noble/ciphers | Viewing key encryption/decryption | | SHA-256 / Keccak256 | @noble/hashes | Key hashing, view tags, nullifiers | | BIP32/BIP39 | @scure/bip32 | Hierarchical key derivation | -| STARK range proofs | Custom (M31 field) | Prove value >= threshold without revealing value | ---