https://github.com/sip-protocol/sipher
Sipher — Privacy-as-a-Skill for Solana Agents. Powered by SIP Protocol.
https://github.com/sip-protocol/sipher
ai-agent hackathon openclaw pedersen-commitments privacy sip-protocol solana stealth-addresses typescript web3
Last synced: 3 months ago
JSON representation
Sipher — Privacy-as-a-Skill for Solana Agents. Powered by SIP Protocol.
- Host: GitHub
- URL: https://github.com/sip-protocol/sipher
- Owner: sip-protocol
- License: mit
- Created: 2026-02-03T17:19:03.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-24T03:32:05.000Z (4 months ago)
- Last Synced: 2026-02-24T09:46:44.309Z (4 months ago)
- Topics: ai-agent, hackathon, openclaw, pedersen-commitments, privacy, sip-protocol, solana, stealth-addresses, typescript, web3
- Language: Python
- Size: 14.2 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
███████╗██╗██████╗ ██╗ ██╗███████╗██████╗
██╔════╝██║██╔══██╗██║ ██║██╔════╝██╔══██╗
███████╗██║██████╔╝███████║█████╗ ██████╔╝
╚════██║██║██╔═══╝ ██╔══██║██╔══╝ ██╔══██╗
███████║██║██║ ██║ ██║███████╗██║ ██║
╚══════╝╚═╝╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝
# Sipher — Privacy-as-a-Skill for Multi-Chain Agents
> **Your agent's wallet is a public diary. Sipher closes the book.**
**REST API + OpenClaw skill that gives any autonomous agent stealth addresses,
hidden amounts, and compliance viewing keys across 17 chains.**
*Stealth addresses • Pedersen commitments • Viewing key hierarchies • On-chain Anchor program • 4 client SDKs*
[]()
[]()
[]()
[]()
[]()
[]()
[]()
[](LICENSE)
**Colosseum Agent Hackathon** | Agent #274 | [Live API](https://sipher.sip-protocol.org) | [Live Demo](https://sipher.sip-protocol.org/v1/demo) | [API Docs](https://sipher.sip-protocol.org/docs) | [Skill File](https://sipher.sip-protocol.org/skill.md)
---
https://github.com/user-attachments/assets/a4a87b0c-7168-4677-b8e6-457debb98cb0
---
## Table of Contents
- [The Problem](#-the-problem)
- [The Solution](#-the-solution)
- [Your First Private Payment](#-your-first-private-payment-in-3-api-calls)
- [Demo Video + Live Demo](#-live-demo-no-api-key-required)
- [What is Sipher?](#-what-is-sipher)
- [Trust Model](#-trust-model)
- [On-Chain Program](#%EF%B8%8F-on-chain-program)
- [Cryptographic Primitives](#-cryptographic-primitives-real-not-mocked)
- [Key Features](#-key-features)
- [Built for Agents, Not Humans](#-built-for-agents-not-humans)
- [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)
- [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)
- [Tech Stack](#%EF%B8%8F-tech-stack)
- [Deployment](#-deployment)
- [Decentralization Roadmap](#%EF%B8%8F-decentralization-roadmap)
- [License](#-license)
---
## 🎯 The Problem
Every agent transaction is a public broadcast. MEV bots, competitors, and surveillance actors can see everything:
❌ Public Agent Transaction
✅ Shielded Agent Transaction (Sipher)
```
Sender: AgentAlice.sol
Recipient: AgentBob.sol
Amount: 50 SOL
Token: wSOL
Time: 2024-02-08 14:30 UTC
```
- 🔴 Sender address exposed → targeted phishing
- 🔴 Recipient known → front-running, sandwich attacks
- 🔴 Amount visible → MEV extraction
- 🔴 Pattern analysis → trading strategy leaked
- 🔴 Counterparty graph → competitive intelligence
```
Sender:
Recipient:
Amount:
Proof:
Audit:
```
- ✅ Stealth address → unlinkable sender
- ✅ One-time address → no recipient reuse
- ✅ Hidden amount → Pedersen commitment
- ✅ Compliance → selective disclosure via viewing keys
- ✅ On-chain proof → verifiable without revealing data
---
## 💡 The Solution
Sipher sits between your agent and the blockchain, adding privacy primitives to every transaction:
```
Agent (Claude, LangChain, CrewAI, OpenClaw, etc.)
│
▼ REST API (any language, any framework)
┌──────────────────────────────────────────────────────────────────┐
│ Sipher API │
│ Express 5 + TypeScript │ 71 endpoints │ Tiered rate limiting │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Auth │ │ Rate │ │ Idempot- │ │ Audit │ │
│ │ (tiered) │ │ Limit │ │ ency │ │ Log │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └─────────────┼───────────┼─────────────┘ │
└─────────────────────┼───────────┼────────────────────────────────┘
│ │
┌────────────┴───────────┴────────────┐
▼ ▼
┌──────────────────┐ ┌───────────────────────┐
│ @sip-protocol │ │ Solana Mainnet │
│ /sdk v0.7.4 │ │ │
│ │ │ Program: │
│ • Ed25519 ECDH │ │ S1PMFs...9at │
│ • secp256k1 │ │ │
│ • Pedersen │ │ Config PDA: │
│ • XChaCha20 │ │ BVawZk...WZwZ │
│ • BIP32 keys │ │ │
│ • Anchor txs │ │ ZK Verifier: │
│ • Range proofs │ │ Sunspot (roadmap) │
│ • 17 chains │ │ │
└──────────────────┘ └───────────────────────┘
```
---
## 🚀 Your First Private Payment in 3 API Calls
No setup, no SDK, no wallet. Just `curl`.
**Step 1 — Generate a stealth meta-address (recipient side):**
```bash
curl -s -X POST https://sipher.sip-protocol.org/v1/stealth/generate \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"chain": "solana"}' | jq '.data.metaAddress'
```
Returns spending + viewing public keys (base58 for Solana). Share these with the sender.
**Step 2 — Derive a one-time stealth address (sender side):**
```bash
curl -s -X POST https://sipher.sip-protocol.org/v1/stealth/derive \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"recipientMetaAddress": {
"spendingKey": "",
"viewingKey": "",
"chain": "solana"
}
}' | jq '.data.stealthAddress'
```
Returns an unlinkable one-time address. No one can connect it to the recipient.
**Step 3 — Build a shielded transfer:**
```bash
curl -s -X POST https://sipher.sip-protocol.org/v1/transfer/shield \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"senderAddress": "YourSolanaAddress",
"recipientMetaAddress": {
"spendingKey": "",
"viewingKey": "",
"chain": "solana"
},
"amount": "1000000000",
"mint": "So11111111111111111111111111111111111111112"
}' | jq '.data'
```
Returns an unsigned transaction + Pedersen commitment. Sign and submit to Solana.
**Or see everything at once (no API key needed):**
```bash
curl -s https://sipher.sip-protocol.org/v1/demo | jq '.data.summary'
```
---
## 🎥 Live Demo (No API Key Required)
25 real cryptographic operations executing live — no mocks, no fakes:
```bash
curl https://sipher.sip-protocol.org/v1/demo | jq '.data.summary'
```
```json
{
"stepsCompleted": 25,
"endpointsExercised": 35,
"cryptoOperations": 37,
"allPassed": true,
"chainsDemo": ["solana", "ethereum", "near", "cosmos"],
"realCrypto": [
"Ed25519 ECDH (stealth addresses)",
"secp256k1 ECDH (EVM/Cosmos stealth)",
"Pedersen commitments (homomorphic)",
"XChaCha20-Poly1305 (viewing key encryption)",
"BIP32 hierarchical key derivation",
"STARK range proofs (M31 limbs)",
"Keccak256 nullifier derivation (governance)"
]
}
```
---
## 🛡️ What is Sipher?
Sipher wraps [SIP Protocol](https://sip-protocol.org)'s privacy SDK as a **REST API** and **OpenClaw-compatible skill**. Any autonomous agent — Claude, LangChain, CrewAI, OpenClaw, or raw HTTP — can call Sipher to transact privately across 17 blockchains.
Think of it like upgrading from HTTP to HTTPS, but for agent transactions:
```
Public Transactions → Sipher API → Private Transactions
(everyone sees) (one call) (only you and your auditor see)
```
---
## 🔐 Trust Model
Agents trusting a REST API with cryptographic material is a real concern. Here's exactly what Sipher sees at each endpoint:
| Endpoint | Server Sees | Server Does NOT See | Trust Level |
|----------|-------------|---------------------|-------------|
| `/stealth/generate` | `chain` param | — (keys generated & returned, not stored) | **Low** |
| `/stealth/derive` | Meta-address public keys | Recipient private keys | **Low** |
| `/stealth/check` | Both private keys (ephemeral) | — | **High** |
| `/transfer/shield` | Sender, meta-address, amount | Recipient private keys | **Medium** |
| `/transfer/claim` | Spending + viewing private keys | — | **Critical** |
| `/commitment/create` | Plaintext value | — (commitment hides on-chain) | **Medium** |
| `/viewing-key/disclose` | Viewing key + plaintext tx data | — | **High** |
| `/viewing-key/decrypt` | Viewing key + ciphertext | — | **High** |
| `/scan/assets` | Stealth address (public) | Private keys | **Low** |
**Mitigations:**
- **Stateless server** — no keys, private data, or session secrets are persisted. Every request is independent.
- **Audit log redaction** — all private keys, blinding factors, and viewing keys are automatically redacted (`[REDACTED]`) in structured logs.
- **Zero-trust alternative** — for maximum security, agents can use [`@sip-protocol/sdk`](https://github.com/sip-protocol/sdk) directly. Same cryptographic primitives, no server involved.
- **`/transfer/claim` caveat** — this is a convenience endpoint. Production agents should derive stealth keys client-side using the SDK and only submit the resulting transaction.
---
## ⛓️ On-Chain Program
Sipher's privacy operations are backed by a deployed Solana Anchor program:
| Field | Value |
|-------|-------|
| **Program ID** | `S1PMFspo4W6BYKHWkHNF7kZ3fnqibEXg3LQjxepS9at` |
| **Config PDA** | `BVawZkppFewygA5nxdrLma4ThKx8Th7bW4KTCkcWTZwZ` |
| **Fee Collector** | `S1P6j1yeTm6zkewQVeihrTZvmfoHABRkHDhabWTuWMd` |
| **Network** | Solana Mainnet-Beta |
| **Features** | Transfer records (PDA), Pedersen commitments, viewing key hashes |
| **SDK Function** | `shieldedTransfer()` — builds Anchor instructions with discriminators |
| **ZK Verifier** | SunspotVerifier — Noir → Groth16 (in SDK, integration roadmap) |
The `transfer/shield` endpoint builds unsigned transactions targeting this program. The SDK's `shieldedTransfer()` constructs the full Anchor instruction with account discriminators, PDA derivation for transfer records, and commitment data embedding.
---
## 🔬 Cryptographic Primitives (Real, Not Mocked)
Every crypto operation uses audited, production-grade libraries:
| Primitive | Library | What It Does |
|-----------|---------|-------------|
| **Ed25519 Stealth** | `@noble/curves` | One-time addresses via ECDH (Solana, NEAR, Move) |
| **secp256k1 Stealth** | `@noble/curves` | EVM, Cosmos, Bitcoin stealth addresses |
| **Pedersen Commitments** | `@sip-protocol/sdk` | Homomorphic hidden amounts (add, subtract, verify) |
| **XChaCha20-Poly1305** | `@noble/ciphers` | Viewing key encryption/decryption (AEAD) |
| **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.
---
## ✨ Key Features
- **Agent-First REST API** — any language, any framework, just HTTP
- **17-Chain Stealth Addresses** — auto curve detection (ed25519/secp256k1)
- **Homomorphic Pedersen Commitments** — add and subtract hidden amounts
- **Compliance Viewing Keys** — BIP32 hierarchy, selective disclosure, auditor encryption
- **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
- **OpenClaw Skill File** — `GET /skill.md` for agent discovery
- **Live Demo** — `GET /v1/demo` runs 25 real crypto operations, no auth required
---
## 🤖 Built for Agents, Not Humans
Sipher isn't a human tool with an API bolted on. Every design decision prioritizes autonomous agents:
| 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`. |
| **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. |
| **Economy** | Usage metering + daily quotas + tiered billing (free/pro/enterprise). Agents can check quota at `/v1/billing/usage` and plan operations. Pay-per-use infrastructure for the agent economy. |
**Autonomous agent demo (zero human intervention):**
```bash
npx tsx scripts/privacy-demo-agent.ts
# 20 steps: generate → derive → shield → scan → claim → encrypt → disclose → govern → tally
```
**Multi-agent payment demo (Alice → Bob → Auditor):**
```bash
npx tsx scripts/multi-agent-demo.ts
# 5 acts: setup → payment → discovery → claim → compliance (17 endpoints)
```
**LangChain tool integration:**
```typescript
// Sipher works as a LangChain StructuredTool — no special SDK needed
class SipherStealthGenerate extends StructuredTool {
name = 'sipher_stealth_generate'
description = 'Generate a stealth meta-address for private payments'
schema = z.object({ chain: z.string().optional() })
async _call({ chain }: { chain?: string }) {
const res = await fetch('https://sipher.sip-protocol.org/v1/stealth/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-API-Key': process.env.SIPHER_KEY! },
body: JSON.stringify({ chain: chain || 'solana' }),
})
return JSON.stringify((await res.json()).data.metaAddress)
}
}
// Works with: LangChain, CrewAI, AutoGPT, OpenClaw, any tool-calling framework
// Full example: npx tsx scripts/langchain-tool-example.ts
```
---
## Performance
Core endpoint latency (localhost, Node.js 22, Apple M-series):
| Endpoint | p50 | p95 | p99 |
|----------|-----|-----|-----|
| `/v1/stealth/generate` | 3ms | 5ms | 7ms |
| `/v1/stealth/derive` | 2ms | 4ms | 6ms |
| `/v1/commitment/create` | 1ms | 3ms | 4ms |
| `/v1/commitment/verify` | 1ms | 2ms | 3ms |
| `/v1/transfer/shield` | 8ms | 14ms | 18ms |
| `/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`
---
## 📊 What's Real vs. What's Preview
Judges reward transparency. Here's exactly what's production-grade and what's interface-ready with mock backends:
| Feature | Status | Details |
|---------|--------|---------|
| Stealth addresses (17 chains) | ✅ **Production** | Ed25519 + secp256k1 via `@noble/curves` |
| Pedersen commitments | ✅ **Production** | Homomorphic add/subtract/verify |
| Viewing keys + hierarchy | ✅ **Production** | XChaCha20-Poly1305, BIP32 derivation |
| Shielded transfers | ✅ **Production** | Unsigned tx building (SOL + SPL) |
| Chain-agnostic private transfer | ✅ **Production** | Solana + EVM + NEAR dispatch |
| Privacy scoring | ✅ **Production** | Multi-factor 0-100 analysis |
| Anchor program | ✅ **Deployed** | `S1PMFs...` on mainnet with PDA records |
| SunspotVerifier (Noir → Groth16) | 🔶 Roadmap | Circuit compilation + on-chain verifier (in SDK, not yet integrated) |
| HeliusProvider | ✅ **Production** | DAS API `getAssetsByOwner` at `/v1/scan/assets` |
| Payment scanning | ✅ **Production** | Stealth payment detection via viewing keys |
| Governance voting | ✅ **Production** | Encrypted ballots, nullifiers, homomorphic tally |
| Backend comparison | ✅ **Production** | Weighted scoring across 3 backends |
| Session management | ✅ **Production** | CRUD with ownership, TTL, defaults merge |
| Billing + quotas | ✅ **Production** | Daily quotas, subscriptions, invoices |
| Arcium MPC | 🧪 **Preview** | Production interface, mock computation backend |
| Inco FHE | 🧪 **Preview** | Production interface, mock encryption backend |
| Private swap | 🧪 **Preview** | Jupiter DEX integration stubbed |
| STARK range proofs | 🧪 **Preview** | Hash-based placeholder (real Stwo/Murkl WASM roadmapped) |
| Jito gas abstraction | ✅ **Production** | Real Jito Block Engine JSON-RPC (dual-mode: real when configured, mock fallback) |
---
## 🚀 Quick Start
```bash
# Clone and install
git clone https://github.com/sip-protocol/sipher.git
cd sipher
pnpm install
# Start dev server
pnpm dev
# Run tests (573 tests, 36 suites)
pnpm test -- --run
# Type check
pnpm typecheck
```
### Core Privacy Flows
**1. Generate a stealth meta-address:**
```bash
curl -X POST http://localhost:5006/v1/stealth/generate \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"chain": "solana"}'
```
**2. Create a Pedersen commitment (hidden amount):**
```bash
curl -X POST http://localhost:5006/v1/commitment/create \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"value": "1000000000"}'
```
**3. Encrypt transaction data for an auditor:**
```bash
curl -X POST http://localhost:5006/v1/viewing-key/generate \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"path": "m/0"}'
```
### Live Demo (no auth):
```bash
curl https://sipher.sip-protocol.org/v1/demo | jq .
```
---
## 📦 SDK Depth (@sip-protocol/sdk v0.7.4)
Sipher is powered by the full SIP Protocol SDK — not a thin wrapper:
| 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 |
| `kit-compat` | @solana/kit bridge (modern Solana stack) | ✅ Production |
| `transaction-builder` | Compute budget, priority fees, versioned txs | ✅ Production |
| `ephemeral-keys` | Secure generation, batch ops, crypto disposal | ✅ Production |
| `rpc-client` | Retry, fallback, Tor/SOCKS5 privacy | ✅ Production |
---
## 🔌 API Endpoints (71 total)
**Base URL:** `https://sipher.sip-protocol.org` | **Auth:** `X-API-Key` header | **Docs:** [`/docs`](https://sipher.sip-protocol.org/docs)
All responses follow: `{ success: boolean, data?: T, error?: { code, message, details? } }`
| Category | Count | Endpoints | Description |
|----------|-------|-----------|-------------|
| **Health & Meta** | 5 | `/v1/health`, `/v1/ready`, `/v1/errors`, `/v1/demo`, `/v1/openapi.json` | Status, readiness, error catalog, live demo |
| **Stealth** | 4 | `/v1/stealth/generate`, `/derive`, `/check`, `/generate/batch` | Multi-chain stealth addresses (17 chains) |
| **Transfer** | 3 | `/v1/transfer/shield`, `/claim`, `/private` | Shielded SOL/SPL + chain-agnostic private transfer |
| **Scan** | 3 | `/v1/scan/payments`, `/payments/batch`, `/assets` | Payment detection + Helius DAS asset queries |
| **Commitment** | 5 | `/v1/commitment/create`, `/verify`, `/add`, `/subtract`, `/create/batch` | Pedersen commitments (homomorphic math) |
| **Viewing Key** | 5 | `/v1/viewing-key/generate`, `/derive`, `/verify-hierarchy`, `/disclose`, `/decrypt` | Hierarchical compliance keys + encryption |
| **Proofs** | 8 | `/v1/proofs/range/*`, `/funding/*`, `/validity/*`, `/fulfillment/*` | STARK range proofs + ZK proof types |
| **Backends** | 4 | `/v1/backends`, `/:id/health`, `/select`, `/compare` | Privacy backend registry + comparison engine |
| **C-SPL** | 3 | `/v1/cspl/wrap`, `/unwrap`, `/transfer` | Confidential SPL token operations |
| **Arcium** | 3 | `/v1/arcium/compute`, `/compute/:id/status`, `/decrypt` | MPC computation (preview) |
| **Inco** | 3 | `/v1/inco/encrypt`, `/compute`, `/decrypt` | FHE encryption (preview) |
| **Swap** | 1 | `/v1/swap/private` | Jupiter DEX private swap (preview) |
| **Sessions** | 4 | `/v1/sessions` CRUD | Agent session defaults (pro+) |
| **Governance** | 4 | `/v1/governance/ballot/encrypt`, `/submit`, `/tally`, `/tally/:id` | Encrypted voting + homomorphic tally |
| **Compliance** | 3 | `/v1/compliance/disclose`, `/report`, `/report/:id` | Selective disclosure + audit reports (enterprise) |
| **Jito** | 2 | `/v1/jito/relay`, `/bundle/:id` | Gas abstraction via Jito bundles (preview) |
| **Billing** | 6 | `/v1/billing/usage`, `/subscription`, `/subscribe`, `/invoices`, `/portal`, `/webhook` | Usage tracking + subscriptions |
| **Admin** | 5 | `/v1/admin/keys` CRUD, `/tiers` | API key management |
| **RPC** | 1 | `/v1/rpc/providers` | Provider configuration |
| **Privacy** | 1 | `/v1/privacy/score` | Wallet privacy analysis (0-100) |
Full interactive reference: [`/docs`](https://sipher.sip-protocol.org/docs) | OpenClaw skill: [`/skill.md`](https://sipher.sip-protocol.org/skill.md)
---
## 🌐 Multi-Chain Support (17 Chains)
Stealth address endpoints support 17 chains across 6 families with automatic curve detection:
| Chain Family | Chains | Curve | Key Size |
|-------------|--------|-------|----------|
| **Solana** | solana | ed25519 | 32 bytes |
| **NEAR** | near | ed25519 | 32 bytes |
| **Move** | aptos, sui | ed25519 | 32 bytes |
| **EVM** | ethereum, polygon, arbitrum, optimism, base | secp256k1 | 33 bytes |
| **Cosmos** | cosmos, osmosis, injective, celestia, sei, dydx | secp256k1 | 33 bytes |
| **Bitcoin** | bitcoin, zcash | secp256k1 | 33 bytes |
All `/stealth/*` endpoints accept a `chain` parameter (default: `solana`). The curve is auto-detected based on chain.
---
## 🔒 Agent Workflow
Complete privacy flow from stealth address generation to auditor disclosure:
```
1. Agent generates stealth meta-address POST /v1/stealth/generate
│
2. Agent shares meta-address with sender (off-chain)
│
3. Sender derives one-time stealth address POST /v1/stealth/derive
│
4. Sender builds shielded transfer POST /v1/transfer/shield
│ Returns: unsigned tx + commitment + viewing key hash
│
5. Sender signs + submits the unsigned transaction to Solana
│
6. Recipient scans for incoming payments POST /v1/scan/payments
│
7. Recipient claims to real wallet POST /v1/transfer/claim
│
8. If audit needed → selective disclosure POST /v1/viewing-key/disclose
│
9. Auditor decrypts with viewing key POST /v1/viewing-key/decrypt
```
Each step uses real cryptographic operations: ECDH key agreement, Pedersen commitments, XChaCha20-Poly1305 encryption, and BIP32 key derivation.
---
## 🏗️ Architecture
```
┌──────────────────────────────────────────────────────────────────────────┐
│ SIPHER API │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Middleware Stack │ │
│ │ Shutdown → RequestID → Helmet → CORS → RateLimit → Auth │ │
│ │ → Metering → Timeout → JSON → Compression → Logger → Audit │ │
│ │ → Session → [Route Handlers] → 404 → Error Handler │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Stealth │ │ Commitment │ │ Viewing Key │ │ Transfer │ │
│ │ 4 endpoints │ │ 5 endpoints │ │ 5 endpoints │ │ 3 endpoints │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Proofs │ │ Governance │ │ Compliance │ │ Sessions │ │
│ │ 8 endpoints │ │ 4 endpoints │ │ 3 endpoints │ │ 4 endpoints │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Backends │ │ Arcium MPC │ │ Inco FHE │ │ Billing │ │
│ │ 4 endpoints │ │ 3 endpoints │ │ 3 endpoints │ │ 6 endpoints │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└────────────────────────────┬─────────────────────────────────────────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Redis │ │ @sip-protocol│ │ Solana │
│ (cache, │ │ /sdk │ │ Mainnet │
│ rate limit, │ │ v0.7.4 │ │ │
│ idempotency)│ │ │ │ Program: │
│ │ │ • Stealth │ │ S1PMFs...9at │
│ Optional — │ │ • Pedersen │ │ │
│ falls back │ │ • XChaCha20 │ │ Config PDA: │
│ to in-memory│ │ • BIP32 │ │ BVawZk...wZ │
└──────────────┘ │ • Anchor │ │ │
│ • 17 chains │ │ │
│ • 17 chains │ │ Helius DAS │
└──────────────┘ └──────────────┘
```
### Middleware Stack (execution order)
```
1. shutdownMiddleware → Reject during graceful shutdown
2. requestIdMiddleware → Generate/preserve X-Request-ID
3. helmet() → Security headers (CSP, HSTS)
4. secureCors → Dynamic CORS
5. rateLimiter → Tiered rate limiting (memory-backed)
6. authenticate → X-API-Key / Bearer token
7. meteringMiddleware → Daily quota check + usage tracking
8. timeoutMiddleware → Per-endpoint timeouts (15-90s)
9. express.json() → Parse JSON (1MB limit)
10. compression() → Gzip
11. requestLogger → pino-http request/response logging
12. auditLog → Structured audit log with field redaction
13. sessionMiddleware → Merge X-Session-Id defaults
14. [route handlers] → API routes
15. notFoundHandler → 404 catch-all
16. errorHandler → Global error handler (ErrorCode enum)
```
---
## 📚 Client SDKs
Auto-generated from the OpenAPI 3.1 specification. TypeScript SDK published to npm:
```bash
npm install @sip-protocol/sipher-client
```
| Language | Package / Directory | Transport | Generated By |
|----------|-------------------|-----------|-------------|
| **TypeScript** | [`@sip-protocol/sipher-client`](https://www.npmjs.com/package/@sip-protocol/sipher-client) | `fetch` | openapi-generator (typescript-fetch) |
| **Python** | `sdks/python` | `urllib3` | openapi-generator (python) |
| **Rust** | `sdks/rust` | `reqwest` | openapi-generator (rust) |
| **Go** | `sdks/go` | `net/http` | openapi-generator (go) |
```bash
# Regenerate all SDKs
pnpm sdks:generate
```
CI workflow auto-regenerates SDKs on spec changes (`.github/workflows/generate-sdks.yml`).
---
## 🧪 Test Suite (573 tests, 36 suites)
| Test File | Tests | What It Covers |
|-----------|-------|----------------|
| `health.test.ts` | 13 | Health, ready, root, skill, 404, request ID, program metadata |
| `stealth.test.ts` | 10 | Generate, derive, check (ed25519 + secp256k1) |
| `commitment.test.ts` | 16 | Create, verify, add, subtract, batch |
| `transfer-shield.test.ts` | 12 | Shielded transfer building |
| `transfer-claim.test.ts` | 8 | Stealth key derivation + claim |
| `scan.test.ts` | 12 | Payment scanning + batch |
| `scan-assets.test.ts` | 12 | Helius DAS asset queries + fallback |
| `viewing-key.test.ts` | 10 | Generate, disclose, decrypt |
| `viewing-key-hierarchy.test.ts` | 11 | BIP32 derive, verify, multi-level |
| `middleware.test.ts` | 5 | Auth, CORS, rate limiting |
| `error-codes.test.ts` | 10 | Enum, catalog, error-handler integration |
| `openapi.test.ts` | 6 | Spec validity, paths, auth, tags |
| `audit-log.test.ts` | 8 | Redaction, integration |
| `idempotency.test.ts` | 8 | Cache, replay, validation |
| `batch.test.ts` | 15 | Stealth, commitment, scan batch ops |
| `privacy-score.test.ts` | 10 | Scoring, factors, validation |
| `rpc-provider.test.ts` | 14 | Factory, providers, masking, endpoint |
| `private-transfer.test.ts` | 25 | Solana/EVM/NEAR, validation, idempotency |
| `range-proof.test.ts` | 18 | Generate, verify, M31 math, edge cases |
| `backends.test.ts` | 17 | List, health, select, edge cases |
| `arcium.test.ts` | 18 | Compute, status, decrypt, idempotency |
| `inco.test.ts` | 20 | Encrypt, compute, decrypt, E2E |
| `private-swap.test.ts` | 20 | Happy path, validation, idempotency |
| `backend-comparison.test.ts` | 23 | Scoring, prioritize, cache, edge cases |
| `session.test.ts` | 28 | CRUD, middleware merge, tier gating |
| `governance.test.ts` | 24 | Encrypt, submit, tally, double-vote, E2E |
| `compliance.test.ts` | 23 | Disclose, report, tier gating, auditor verify |
| `jito.test.ts` | 25 | Relay, bundle status, tier gating, state machine, real mode |
| `billing.test.ts` | 31 | Usage, quotas, metering, subscriptions, webhooks |
| `demo.test.ts` | 12 | Live demo (25 steps, all crypto, no auth) |
| *+ 6 more* | 67 | C-SPL, proofs, admin, OpenAPI |
```bash
pnpm test -- --run
```
---
## 🛠️ Tech Stack
| Layer | Technology |
|-------|------------|
| **Runtime** | Node.js 22 (LTS) |
| **Framework** | Express 5 |
| **Language** | TypeScript (strict mode) |
| **Privacy SDK** | @sip-protocol/sdk v0.7.4 |
| **Blockchain** | @solana/web3.js, @solana/spl-token |
| **Crypto** | @noble/curves, @noble/hashes, @noble/ciphers, @scure/bip32 |
| **Validation** | Zod v3 |
| **Logging** | Pino v9 (structured JSON) |
| **Cache** | Redis 7 (optional, in-memory fallback) |
| **Testing** | Vitest + Supertest |
| **Docs** | OpenAPI 3.1 + Swagger UI |
| **Deploy** | Docker + GHCR + GitHub Actions |
| **Domain** | sipher.sip-protocol.org |
---
## 🚢 Deployment
```bash
# Docker (with Redis)
docker compose up -d
# Environment variables
cp .env.example .env
```
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SOLANA_RPC_URL` | Yes | Solana RPC endpoint |
| `SOLANA_RPC_URL_FALLBACK` | No | Fallback RPC (auto-switches on failure) |
| `API_KEYS` | No | Comma-separated API keys |
| `ADMIN_API_KEY` | No | Admin API key for key management |
| `RPC_PROVIDER` | No | RPC provider: `helius`, `quicknode`, `triton`, `generic` |
| `RPC_PROVIDER_API_KEY` | No | API key for premium RPC provider |
| `REDIS_URL` | No | Redis connection URL (falls back to in-memory) |
| `STRIPE_WEBHOOK_SECRET` | No | Stripe webhook signing secret |
| `CORS_ORIGINS` | No | Allowed CORS origins |
### Rate Limits
| Tier | Requests/Hour | Daily Quota | Features |
|------|---------------|-------------|----------|
| Free | 100 | 1,000 ops | Basic endpoints |
| Pro | 10,000 | 100,000 ops | All endpoints + sessions |
| Enterprise | 100,000 | Unlimited | All endpoints + compliance + priority |
---
## 🗺️ Decentralization Roadmap
Sipher is infrastructure, not just an API. Here's the path from convenience layer to protocol:
| Phase | Timeline | What | Trust Model |
|-------|----------|------|-------------|
| **Phase 1** (now) | Q1 2026 | Centralized REST API | Agent trusts server (stateless, key-redacting audit logs) |
| **Phase 2** | Q2 2026 | On-chain privacy program expansion | Stealth derivation + commitment verification as CPI-able Solana instructions. Jupiter/Raydium can compose directly. |
| **Phase 3** | Q3 2026 | Decentralized protocol | On-chain registry of stealth meta-addresses, fee accrual to protocol, network effects. REST API becomes optional convenience layer. |
**Phase 2 expands the existing mainnet program** ([`S1PMFspo4W6BYKHWkHNF7kZ3fnqibEXg3LQjxepS9at`](https://solscan.io/account/S1PMFspo4W6BYKHWkHNF7kZ3fnqibEXg3LQjxepS9at)) with CPI-able instructions — any Solana program can add privacy natively, without HTTP calls.
**Why start centralized?** Iteration speed. A REST API lets us battle-test the crypto, refine the agent UX, and ship 71 endpoints in 10 days. The on-chain migration preserves the same primitives (stealth addresses, Pedersen commitments, viewing keys) while removing the trust assumption.
---
## 📄 License
MIT — see [LICENSE](LICENSE)
---
**Colosseum Agent Hackathon** | Agent #274
*Your agent's wallet is a public diary. Sipher closes the book.*
[Live Demo](https://sipher.sip-protocol.org/v1/demo) · [API Docs](https://sipher.sip-protocol.org/docs) · [Skill File](https://sipher.sip-protocol.org/skill.md) · [Report Bug](https://github.com/sip-protocol/sipher/issues)