sip-protocol/sip-protocol

## 目录 - [什么是 SIP？](#-what-is-sip) - [快速预览](#-quick-preview) - [面临的问题](#-the-problem) - [解决方案](#-the-solution) - [核心功能](#-key-features) - [安装说明](#-installation) - [快速开始](#-quick-start) - [架构设计](#%EF%B8%8F-architecture) - [包](#-packages) - [基础设施](#-infrastructure) - [路线图](#-roadmap) - [技术栈](#%EF%B8%8F-tech-stack) - [开发指南](#-development) - [贡献指南](#-contributing) - [安全说明](#-security) - [许可证](#-license) - [致谢](#-acknowledgments) ## 🛡️ 什么是 SIP？ SIP (Shielded Intents Protocol) 为跨链交易带来了 **HTTPS 级别的隐私保护**。正如 HTTPS 在不改变用户浏览方式的情况下加密了网络，SIP 在不改变用户兑换方式的情况下，为区块链 intents 增加了隐私保护。 ``` HTTP → HTTPS (Web privacy upgrade) Intents → SIP (Blockchain privacy upgrade) ``` **停止暴露你的财务活动。开始私密兑换。** ## 🎥 快速预览 ### 隐私升级

❌ 公开 Intent（所有人可见）	✅ 屏蔽 Intent（Solver 只能看到必要信息）
``` { from: "0x1234...", inputAmount: 10, inputToken: "SOL", outputToken: "ETH", recipient: "0x5678..." } ``` **已暴露：** - 🔴 你的钱包地址 - 🔴 精确金额 - 🔴 接收方地址 - 🔴 完整的交易历史	``` { intentId: "abc123", outputToken: "ETH", minOutput: 0.004, inputCommitment: "0xabc...", recipientStealth: "0xdef...", proof: "0x123..." } ``` **已保护：** - ✅ 发送方隐藏 (commitment) - ✅ 金额隐藏 (ZK proof) - ✅ 接收方隐藏 (stealth address) - ✅ 不可关联的交易

**结果：** Solver 可以在不知道你是谁或资金流向哪里的情况下完成你的 intent。 ## 🎯 面临的问题 当前的跨链解决方案会暴露你交易的**所有**信息。这不仅是不便，更是一种安全风险。 ### 暴露的信息 | 数据点 | 可见性 | 风险 | |------------|------------|------| | **发送方地址** | 公开 | 定向钓鱼、社会工程学攻击 | | **交易金额** | 公开 | 抢跑、MEV 提取 | | **接收方地址** | 公开 | 监控、地址聚类 | | **交易历史** | 永久 | 财务画像、歧视 | ### 现实世界的后果 | 攻击向量 | 工作原理 | 影响 | |---------------|--------------|--------| | **抢跑 (Front-Running)** | 机器人看到你待处理的兑换并抢先执行 | 你得到更差的价格 | | **MEV 提取** | 验证者重新排序交易以获利 | 你的价值被提取 | | **钓鱼** | 攻击者识别高价值钱包 | 直接盗窃尝试 | | **监控** | 交易所/政府追踪所有活动 | 隐私侵犯 | | **价格歧视** | 服务看到你的余额 | 向富有用户收取更高费用 | **区块链是一个公共账本。没有隐私，它就是一个监控系统。** ## 💡 解决方案 SIP 使用来自 Zcash 的久经考验的技术和尖端的隐身地址方案，将跨链 intents 封装在一个**加密隐私层**中。 ### 工作原理 ``` ┌─────────────────────────────────────────────────────────────────┐ │ USER │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ SIP SDK │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ │ │ Privacy │ │ Stealth │ │ ZK Proof │ │ │ │ │ │ Toggle │ │ Address Gen │ │ Generation │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ │ └─────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ SHIELDED INTENT LAYER │ │ │ │ • Pedersen commitments (hide amounts) │ │ │ │ • Stealth addresses (hide recipients) │ │ │ │ • ZK proofs (prove validity without revealing data) │ │ │ └─────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ NEAR INTENTS ROUTER │ │ │ │ • Intent matching │ │ │ │ • Solver network │ │ │ │ • Cross-chain execution │ │ │ └─────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Solana │ │ Zcash │ │ Ethereum │ │ │ │ │ │ (Privacy │ │ │ │ │ │ │ │ Backbone) │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 核心机制 | 机制 | 目的 | 技术 | |-----------|---------|------------| | **Pedersen Commitments** | 隐藏交易金额 | `value * G + blinding * H` | | **隐身地址** | 一次性接收方地址 | EIP-5564 风格，secp256k1 | | **ZK Proofs** | 在不泄露数据的情况下证明有效性 | Zcash 证明系统 | | **Viewing Keys** | 用于合规的选择性披露 | 派生密钥对 | ## ✨ 核心功能 ### 🔒 **一键隐私** 通过一个开关在公开模式和屏蔽模式之间切换。无需复杂的设置，没有密钥管理的烦恼。 ### 🌐 **多链支持** 适用于 Solana、Ethereum、NEAR 等网络。隐私不应局限于特定链。 ### 📊 **三个隐私级别** | 级别 | 描述 | 用例 | |-------|-------------|----------| | `TRANSPARENT` | 标准公开交易 | 不需要隐私时 | | `SHIELDED` | 通过 Zcash 池实现完全隐私 | 个人交易 | | `COMPLIANT` | 隐私 + viewing key | 机构/监管 | ### 👻 **隐身地址** 每笔交易都使用一个新的一次性地址。没有地址重用，没有交易可链接性。 ### 🔑 **Viewing Keys** 用于审计和合规的选择性披露。证明你的交易历史，而无需向所有人公开。 ### 🛡️ **MEV 保护** 隐藏的金额和接收方意味着抢跑者无法从你的交易中提取价值。 ### ⚡ **零 UX 摩擦** 你熟悉的兑换界面。隐私在底层自动完成。 ## 📦 安装说明 ``` # npm npm install @sip-protocol/sdk # pnpm pnpm add @sip-protocol/sdk # yarn yarn add @sip-protocol/sdk ``` ## 🚀 快速开始 ### 1. 初始化 SDK ``` import { SIP, PrivacyLevel } from '@sip-protocol/sdk'; const sip = new SIP({ network: 'mainnet', // NEAR Intents is mainnet-only (no testnet) }); ``` ### 2. 创建屏蔽 Intent ``` const intent = await sip.createIntent({ input: { chain: 'solana', token: 'SOL', amount: 10, }, output: { chain: 'ethereum', token: 'ETH', }, privacy: PrivacyLevel.SHIELDED, }); ``` ### 3. 获取报价并执行 ``` // Solvers compete to fill your intent const quotes = await intent.getQuotes(); // Execute with the best quote const result = await intent.execute(quotes[0]); console.log(result.status); // 'fulfilled' console.log(result.txHash); // null (shielded!) console.log(result.proof); // ZK proof of execution ``` ### 4. 选择你的隐私级别 ``` // Public mode (standard intent, no privacy) privacy: PrivacyLevel.TRANSPARENT // Full privacy (via Zcash shielded pool) privacy: PrivacyLevel.SHIELDED // Privacy + audit capability (for institutions) privacy: PrivacyLevel.COMPLIANT, viewingKey: generateViewingKey() ``` ## 🏗️ 架构设计 ### 组件概览 ``` sip-protocol/ ├── examples/ # Integration examples │ ├── private-swap/ # Private swap example │ ├── private-payment/ # Stealth payment example │ └── compliance/ # Viewing key example ├── packages/ │ ├── sdk/ # @sip-protocol/sdk │ │ ├── src/stealth.ts # Stealth address generation │ │ ├── src/intent.ts # Intent builder │ │ ├── src/privacy.ts # Viewing key management │ │ ├── src/crypto.ts # Pedersen commitments │ │ └── src/sip.ts # Main client class │ └── types/ # @sip-protocol/types │ ├── src/intent.ts # ShieldedIntent interface │ ├── src/privacy.ts # PrivacyLevel enum │ └── src/stealth.ts # Stealth address types └── docs/ # Documentation ``` ### 数据流 ``` User Input → Privacy Layer → Intent Creation → Solver Network → Execution │ │ │ │ │ │ ▼ │ │ │ │ ┌──────────┐ │ │ │ │ │ Generate │ │ │ │ │ │ Stealth │ │ │ │ │ │ Address │ │ │ │ │ └──────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌──────────┐ │ │ │ │ │ Create │ │ │ │ │ │ Pedersen │ │ │ │ │ │Commitment│ │ │ │ │ └──────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌──────────┐ │ │ │ │ │ Generate │ │ │ │ │ │ ZK Proof │ │ │ │ │ └──────────┘ │ │ │ │ │ │ │ │ └──────────────┴──────────────┴─────────────────┴─────────────┘ ``` ## 📚 包 | 包 | 版本 | 描述 | 测试 | |---------|---------|-------------|-------| | [`@sip-protocol/sdk`](packages/sdk) | 0.7.3 | 用于屏蔽 intents 的核心 SDK | 6,603 | | [`@sip-protocol/types`](packages/types) | 0.2.1 | TypeScript 类型定义 | - | | [`@sip-protocol/react`](packages/react) | 0.1.0 | 用于 SIP 的 React hooks | 82 | | [`@sip-protocol/cli`](packages/cli) | 0.2.0 | CLI 工具 | 10 | | [`@sip-protocol/api`](packages/api) | 0.1.0 | REST API 封装 | 18 | | [`@sip-protocol/react-native`](packages/react-native) | 0.1.1 | iOS/Android SDK | 10 | | [`circuits`](packages/circuits) | - | Noir ZK circuits | - | **链上程序：** | 程序 | 描述 | |---------|-------------| | [`sip-privacy`](programs/sip-privacy) | Solana Anchor program | | [`sip-ethereum`](contracts/sip-ethereum) | Ethereum Foundry contracts | **示例：** [`examples/`](examples/) 中有 11 个集成示例 ## 🔌 基础设施 SIP 是**与基础设施无关**的——使用你偏好的 RPC 提供商，而无需更改你的应用程序代码。 ### Solana RPC 提供商 | 提供商 | 最适合 | 实时 | 特殊功能 | |----------|----------|-----------|------------------| | **[Helius](https://helius.dev)** | 生产级应用 | Webhooks | DAS API，丰富的元数据 | | **[QuickNode](https://quicknode.com)** | 企业级 | Yellowstone gRPC | 全球边缘网络 | | **[Triton](https://triton.one)** | DeFi/交易 | Dragon's Mouth gRPC | ~400ms 延迟优势 | | **通用** | 开发 | WebSocket | 无需 API key | ``` import { createProvider } from '@sip-protocol/sdk' // Same API, different backends — your choice const provider = createProvider('quicknode', { endpoint: process.env.QUICKNODE_ENDPOINT }) // or: createProvider('helius', { apiKey: process.env.HELIUS_API_KEY }) // or: createProvider('triton', { xToken: process.env.TRITON_TOKEN }) // or: createProvider('generic', { connection }) // All providers work identically const assets = await provider.getAssetsByOwner('7xK9...') ``` ### 为什么与提供商无关？ - **无供应商锁定** — 无需更改代码即可切换提供商 - **同类最佳** — 使用 Helius 进行 DAS 操作，使用 QuickNode 进行 gRPC 操作，混合搭配 - **开源工具** — 统一接口使整个生态系统受益 - **弹性** — 提供商之间的轻松故障转移 有关详细提供商文档，请参见 [SDK README](packages/sdk/README.md)。 ## 🗺️ 路线图 有关详细的里程碑跟踪，请参见 [ROADMAP.md](ROADMAP.md)。 ### 阶段 1-3：基础 ✅ **已完成** (M1-M15) - ✅ 具备隐身地址、Pedersen commitments、viewing keys 的核心 SDK - ✅ 多链支持（包括 Solana、Ethereum、NEAR 在内的 15+ 条链） - ✅ ZK proof 系统（Noir circuits，浏览器证明） - ✅ NEAR Intents + Zcash 集成 - ✅ React、CLI、API 包 - ✅ 6,661+ 测试 ### 阶段 4：同链扩展 🎯 **进行中** (M16-M18) - ✅ M16：叙事捕获（内容、社区、定位） - ✅ M17：Solana 同链隐私（已完成 - 2026 年 1 月） - 🎯 M18：Ethereum 同链隐私（进行中） ### 阶段 5：技术护城河 🔲 **已规划** (M19-M22) - 🔲 M19：证明组合（Zcash + Mina） - 🔲 M20：多语言 SDK（Python, Rust, Go） - 🔲 M21：SIP-EIP 标准提案 - 🔲 M22：机构托管集成 ## 🛠️ 技术栈 | 类别 | 技术 | 用途 | |----------|------------|---------| | **框架** | Next.js 14 (App Router) | 参考应用程序 | | **语言** | TypeScript (严格模式) | 类型安全 | | **样式** | Tailwind CSS + shadcn/ui | UI 组件 | | **状态** | Zustand | 客户端状态管理 | | **Monorepo** | pnpm + Turborepo | 包管理 | | **密码学** | @noble/curves, @noble/hashes | 隐身地址，commitments | | **部署** | Vercel | 托管 | ## 💻 开发指南 ### 前置条件 - Node.js 18+ - pnpm 8+ ### 设置 ``` # Clone repository git clone https://github.com/sip-protocol/sip-protocol.git cd sip-protocol # Install dependencies pnpm install # Start development pnpm dev ``` ### 命令 ``` pnpm dev # Start development server pnpm build # Build all packages pnpm test -- --run # Run all tests (6,661+) pnpm lint # Lint code pnpm typecheck # Type check ``` ## 🤝 贡献指南 我们欢迎各种贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ### 贡献领域 - Protocol 改进 - SDK 功能 - 文档 - 安全审计 - 链集成 ## 🔐 安全说明 SIP 是实验性软件。使用风险自负。 ### 威胁模型 请参阅我们全面的[威胁模型](docs/security/THREAT-MODEL.md)了解： - 已识别的攻击向量及其缓解措施 - 信任假设与安全边界 - 每个威胁类别的严重评级 - 针对用户、集成商和运营商的安全建议 ### Zcash RPC 安全 **关键：** 在生产环境中连接到 Zcash 节点时，请务必使用 HTTPS/TLS。 Zcash RPC 客户端使用 HTTP 基本认证，该认证以 base64 编码的明文形式传输凭据。如果不使用 TLS/HTTPS： - RPC 凭据容易受到网络嗅探攻击 - 所有交易数据都可能被拦截 - 可能发生中间人攻击 **生产环境要求：** - ✅ Zcash RPC endpoint 使用 `https://` URL - ✅ 使用有效的 TLS 证书配置 zcashd - ✅ 将凭据存储在安全的环境变量中 - ✅ 使用网络级访问控制（防火墙规则、VPC） - ❌ 在生产环境中绝不使用 HTTP - ❌ 绝不在源代码中硬编码凭据 **示例：** ``` // ✅ Production (HTTPS) const client = new ZcashRPCClient({ host: 'https://your-node.com', port: 8232, username: process.env.ZCASH_RPC_USER, password: process.env.ZCASH_RPC_PASS, }) // ⚠️ Development only (HTTP on localhost) const testClient = new ZcashRPCClient({ host: '127.0.0.1', port: 18232, username: 'test', password: 'test', testnet: true, }) ``` ### 报告安全问题 如果你发现安全漏洞，请负责任地报告： - 邮箱：security@sip-protocol.xyz - 绝不为安全漏洞创建公开的 issue ## 📄 许可证 [MIT 许可证](LICENSE) — 有关详细信息，请参阅 LICENSE 文件。 ## 🙏 致谢 SIP 站在巨人的肩膀上： - [Zcash](https://z.cash) — 保护隐私的加密货币和证明系统 - [NEAR Protocol](https://near.org) — 以 Intent 为核心的区块链基础设施 - [EIP-5564](https://eips.ethereum.org/EIPS/eip-5564) — 隐身地址标准 - [@noble/curves](https://github.com/paulmillr/noble-curves) — 经过审计的密码学原语 - 更广泛的隐私和密码学研究社区

标签：NEAR协议, TypeScript, Web3, 安全插件, 网络安全, 自动化攻击, 跨链交易, 隐私保护, 零知识证明