zak-li/pekix

## Pekix Pekix 是一个机构级的无信任、隐私保护的偿付能力验证平台。它使金融机构能够向用户和监管机构证明总资产覆盖情况，而无需披露个别账户余额或 compromising 敏感用户数据。Pekix 由零知识证明（ZKP）、Merkle 求和树和链上锚定技术驱动，在链下负债和链上资产之间提供了数学上可验证的桥梁。 ## 目录 - [功能特性](#features) - [环境要求](#requirements) - [快速开始](#quick-start) - [API 参考](#api-reference) - [环境变量](#environment-variables) - [项目结构](#project-structure) - [可观测性](#observability) - [许可证](#license) ## 功能特性 Pekix 的核心是一个 12 步审计流程，负责协调数据验证、密码学承诺和取证分析。它构建了一个域分离的 Merkle 求和树，其中每个节点包含一个 SHA-256 哈希值和累计余额，允许任何用户以 O(log n) 的效率验证其包含性。为了确保机构无法误报总负债，平台生成了一个非交互式 Sigma 协议证明（Schnorr 风格），基于 2048 位 MODP 安全素数群，将总承诺绑定到 Merkle 根。 完整性通过多层取证套件强制执行。系统执行本福特定律分析，结合 Kolmogorov-Smirnov 检验来检测统计上伪造的数据，同时进行深度合规检查，包括制裁、集中风险和重复余额。资产通过 Ethereum JSON-RPC 针对机构控制的钱包进行验证，生成的审计状态被不可变地锚定到 `SolvencyRegistry` 智能合约，以供公众验证。 Pekix 暴露了一个安全的 FastAPI 接口，受 SHA-256 哈希 API 密钥和严格的安全头策略保护。它提供全面的报告产物，包括 LaTeX 渲染的 PDF 证书和通过 LLM 辅助 RAG 流程生成的 MiCA 合规 XML 监管报告。压力测试模块进一步评估偿付能力，以应对市场崩盘、交易所倒闭和严重经济衰退的情况。 ## 环境要求 **API** | 包 | 版本 | 角色 | |---|---|---| | Python | 3.11+ | 运行时 | | FastAPI | 0.129+ | HTTP API 框架 | | pydantic-settings | 2.4+ | 配置管理 | | Web3.py | 7.8+ | Ethereum RPC 客户端 | | Matplotlib | 3.10+ | 取证可视化 | | SciPy | 1.15+ | 统计分析 | | Groq | 0.9+ | 监管 AI | **技术栈** | 组件 | 角色 | |---|---| | Ethereum 节点 | 链上资产验证 | | Hardhat | 智能合约开发 | | PostgreSQL / Supabase | 账户数据存储 | | TeX Live / pdflatex | PDF 报告生成 | | Node.js 18+ | 区块链工具运行时 | ## 快速开始 **步骤 1：克隆和配置** ``` git clone https://github.com/zak-li/pekix.git cd pekix cp .env.example .env ``` 打开 `.env` 并配置 `ADMIN_SECRET`、`SUPABASE_URL` 和 `ETH_RPC_URL`。 **步骤 2：安装依赖** ``` python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt npm install ``` **步骤 3：启动 API** ``` uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload ``` API 在 `http://localhost:8000` 上运行。交互式文档位于 `/docs`（Swagger UI）或 `/redoc`。 **步骤 4：生成 API 密钥** ``` curl -X POST http://localhost:8000/api/v1/auth/generate \ -H "X-Admin-Secret: YOUR_ADMIN_SECRET" \ -H "Content-Type: application/json" \ -d '{"name": "auditor-1", "role": "auditor", "institution": "Pekix Finance"}' ``` **步骤 5：运行完整审计** ``` curl -X POST http://localhost:8000/api/v1/audit/run \ -H "X-API-Key: YOUR_GENERATED_KEY" ``` ## API 参考 **认证** | 方法 | 端点 | 描述 | |---|---|---| | POST | `/api/v1/auth/generate` | 创建新的 API 密钥（仅限管理员） | **审计操作** | 方法 | 端点 | 描述 | |---|---|---| | POST | `/api/v1/audit/run` | 运行完整的 12 步审计流程 | | GET | `/api/v1/audit/report` | 获取最新的审计证明证书 | | GET | `/api/v1/audit/charts/latest/{file}` | 提供审计可视化图表 | **密码学和包含性验证** | 方法 | 端点 | 描述 | |---|---|---| | POST | `/api/v1/inclusion/verify` | 验证账户在 Merkle 树中的包含性 | | GET | `/api/v1/tree/structure` | 导出完整的 Merkle 求和树 | | GET | `/api/v1/tree/trace/{id}` | 获取 ID 的包含证明和路径 | | POST | `/api/v1/zkp/prove` | 生成新的 ZKP 承诺 | | POST | `/api/v1/zkp/verify` | 验证先前生成的 ZKP | ## 环境变量 **必需** | 变量 | 描述 | |---|---| | `ADMIN_SECRET` | API 密钥生成的头部密钥 | | `FULL_NAME_SIGNATURE` | 报告签名的审计员名称 | | `SUPABASE_URL` | PostgreSQL 连接字符串 | | `ETH_RPC_URL` | Ethereum JSON-RPC 端点 | **可选** | 变量 | 默认值 | 描述 | |---|---|---| | `SOLVENCY_CONTRACT_ADDRESS` | `""` | 已部署的 Registry 地址 | | `GROQ_API_KEY` | `""` | MiCA XML 生成的 API 密钥 | | `BENFORD_RISK_HIGH` | `5.0` | 严重风险的 KS 阈值 | | `STRESS_CRASH_FACTOR` | `0.7` | 崩盘场景的资产乘数 | | `LOG_LEVEL` | `INFO` | 日志详细程度 | ## 项目结构 ``` pekix/ ├── src/ │ ├── api/ # FastAPI routers and middleware │ ├── core/ # Merkle trees, ZKP math, analytics │ ├── services/ # Pipeline orchestration, PDF/XML generation │ ├── infrastructure/ # Blockchain and DB adapters │ └── utils/ # Visualizer, logger, validation ├── blockchain/ │ ├── contracts/ # SolvencyRegistry.sol (0.8.24) │ ├── scripts/ # Deployment and anchoring scripts │ └── test/ # Hardhat contract tests ├── data/ # Local data and hashed key store ├── reports/ # Timestamped audit artifacts └── tests/ # Python test suite ``` ## 可观测性 Pekix 实现了结构化的审计跟踪和取证监控系统。每个流程步骤和 API 请求都通过轮换文件处理程序和唯一请求 ID 进行记录。取证引擎通过自动统计分布和压力测试性能指标提供数据完整性的深度可见性。 | 组件 | 端口 | 描述 | |---|---|---| | FastAPI | 8000 | 主 API 和交互式文档 | | Hardhat 网络 | 8545 | 开发用本地区块链 | 每次审计证明都会捕获自定义审计指标： | 指标 | 描述 | |---|---| | `solvency_ratio` | 资产覆盖负债的百分比 | | `score_benford` | 与自然余额分布的统计偏差 | | `risk_level` | 基于 KS 检验结果分类的风险 | | `data_integrity` | 合规结果（制裁、重复等） | ## 许可证 本项目根据 [Business Source License 1.1](LICENSE) 获得许可。

标签：DeFi, Hardhat, Merkle Sum Tree, MITM代理, Python, SHA-256, Sigma Protocol, Solidity, ZK-SNARK, 偿付能力证明, 区块链, 占用监测, 合规, 审计, 密码学, 手动系统调用, 提示词模板, 无信任系统, 无后门, 智能合约, 测试用例, 监管科技, 资产管理, 逆向工具, 金融科技, 链上验证, 隐私计算, 零知识证明