softnationz/PR-Pulse

# 📡 PR Pulse 协议 [](https://opensource.org/licenses/MIT) [](https://soliditylang.org/) [](https://hardhat.org/) ## 🌟 概述 通过将 GitHub 运营数据与区块链基础设施连接，PR Pulse 创建了不可篡改的审计追踪，涵盖： - 📊 **维护者响应时间** - ⏱️ **拉取请求审查延迟** - 🚧 **工作流瓶颈** - 🎯 **SLA 合规性指标** ### 核心特性 ✅ **去中心化预言机网络** — EIP-191 签名的遥测批次确保数据真实性 ✅ **自动化 SLA 执行** — 智能合约评估指标并触发升级流程 ✅ **可编程激励机制** — 发出悬赏事件以激励外部审查者 ✅ **基于角色的访问控制** — OpenZeppelin AccessControl 实现治理与运营 ✅ **Gas 优化存储** — 高效的结构体打包与存储模式 ✅ **重放保护** — 时序验证防止数据篡改 ## 🏗️ 架构 ### 合约拓扑 ``` PulseConfig (Configuration Hub) ├── Repository Registry ├── SLA Boundaries ├── Maintainer RBAC └── Treasury Addresses │ ▼ PRPulseTelemetry (Data Ingestion) ├── Batch Validation (EIP-191) ├── Chronological Ordering ├── Bottleneck Counters └── PR Snapshot Storage │ ▼ WorkflowEscalationEngine (SLA Enforcement) ├── Threshold Evaluation ├── Sequential Escalation (0→1→2) ├── Bounty Emission Events └── Reentrancy Protection ``` ## 📋 智能合约 ### 核心合约 | 合约 | 描述 | 核心职责 | |----------|-------------|---------------------| | **PulseConfig** | 配置与注册中心 | 仓库接入、SLA 管理、维护者授权 | | **PRPulseTelemetry** | 遥测数据摄取引擎 | 批次验证、签名验证、状态存储 | | **WorkflowEscalationEngine** | SLA 执行与升级管理 | 阈值评估、升级推进、悬赏计算 | ### 辅助组件 | 组件 | 位置 | 用途 | |-----------|----------|---------| | **TelemetryTypes** | `contracts/libraries/` | 标准类型定义与枚举 | | **Interfaces** | `contracts/interfaces/` | 外部集成的合约 ABI | ## 💻 代码示例 ### 1. 接入仓库 ``` // Deploy PulseConfig PulseConfig config = new PulseConfig(governanceMultisig); // Onboard a repository with SLA configuration uint32 repoId = config.onboardRepository( "ethereum/go-ethereum", treasuryAddress ); // Configure custom SLA thresholds TelemetryTypes.RepositorySLA memory sla = TelemetryTypes.RepositorySLA({ maxReviewDelayHours: 48, // Max time before first review maxResponseDelayHours: 24, // Max time for maintainer response maxBlockedDurationHours: 72, // Max time in blocked state gracePeriodHours: 12 // Grace period before escalation }); config.configureSLAConstraints(repoId, sla); ``` ### 2. 提交遥测数据（预言机） ``` // Oracle node prepares telemetry batch const updates = [ { prId: 1234, repoId: 1, status: 1, // OPEN_ACTIVE isBottleneck: true, lastActivityTimestamp: Math.floor(Date.now() / 1000), currentReviewDelayHours: 56, primaryAssignee: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" } ]; // Encode and sign the batch const encoded = ethers.AbiCoder.defaultAbiCoder().encode( ["tuple(uint32,uint32,uint8,bool,uint32,uint32,address)[]"], [updates] ); const hash = ethers.keccak256(encoded); const signature = await oracleWallet.signMessage(ethers.getBytes(hash)); // Submit to blockchain await telemetry.commitTelemetryBatch(updates, signature); ``` ### 3. 评估 SLA 违规 ``` // Keeper bot or external caller triggers evaluation workflowEngine.evaluateAndEscalate(repoId, prId); // Contract logic (simplified): // 1. Fetch PR snapshot from PRPulseTelemetry // 2. Fetch SLA rules from PulseConfig // 3. Compare metrics against thresholds // 4. Advance escalation level if breach detected // 5. Emit events for off-chain systems ``` ### 4. 监听事件 ``` // Monitor SLA breach events telemetry.on("PRTelemetryCommitted", (repoId, prId, status, isBottleneck, delayHours) => { console.log(`PR #${prId} in repo ${repoId}: ${delayHours}h delay`); }); workflowEngine.on("OperationalSLABreachFlagged", (repoId, prId, severity, assignee) => { console.log(`🚨 SLA Breach: Repo ${repoId}, PR ${prId}, Severity ${severity}`); }); workflowEngine.on("CompensationReviewPoolIncentivized", (repoId, prId, bountyWei) => { console.log(`💰 Bounty emitted: ${ethers.formatEther(bountyWei)} ETH`); }); ``` ## 🚀 快速开始 ### 前置条件 - **Node.js** ≥ 20.0.0 - **npm** ≥ 10.0.0 - **Git** ### 安装 ``` # 克隆仓库 git clone https://github.com/your-org/pr-pulse-protocol.git cd pr-pulse-protocol # 安装依赖 npm install # 配置环境 cp .env.example .env # 编辑 .env 配置文件 ``` ### 编译 ``` # 编译智能合约 npx hardhat compile # 运行代码检查工具 npm run lint:sol # 格式化代码 npm run format:fix ``` ### 测试 ``` # 运行所有测试 npx hardhat test # 运行测试并生成覆盖率报告 npm run coverage # 运行特定测试文件 npx hardhat test test/PRPulseTelemetry.test.js ``` ### 部署 ``` # 部署到本地 Hardhat 网络 npx hardhat run scripts/deploy.js --network hardhat # 部署到测试网络（在 hardhat.config.js 中配置网络） npx hardhat run scripts/deploy.js --network sepolia # 填充仓库配置文件 npx hardhat run scripts/seedRepositoryProfiles.js --network hardhat # 模拟预言机遥测数据提交 npx hardhat run scripts/simulateTelemetryOracle.js --network hardhat # 生成升级事件 npx hardhat run scripts/generateEscalationEvents.js --network hardhat ``` ## 📊 数据流 ### 遥测流水线 ``` ┌──────────────┐ │ GitHub Event │ (PR opened, review requested, merged, etc.) └──────┬───────┘ │ ▼ ┌─────────────────┐ │ Webhook Server │ (Captures event payload) └──────┬──────────┘ │ ▼ ┌──────────────────┐ │ Oracle Node │ │ │ │ 1. Parse event │ │ 2. Calculate │ │ metrics │ │ 3. Encode batch │ │ 4. Sign (EIP-191)│ └──────┬───────────┘ │ ▼ ┌────────────────────────┐ │ PRPulseTelemetry.sol │ │ │ │ 1. Verify signature │ │ 2. Check repo registry │ │ 3. Validate timestamps │ │ 4. Update counters │ │ 5. Store snapshot │ │ 6. Emit events │ └────────────────────────┘ ``` ### 升级流程 ``` Level 0 (Normal) │ ├─► Review delay > maxReviewDelayHours │ ▼ Level 1 (Warning) │ Event: OperationalSLABreachFlagged(severity=1) │ ├─► isBottleneck=true AND │ delay > (maxBlockedDurationHours + gracePeriodHours) │ ▼ Level 2 (Critical) │ Event: OperationalSLABreachFlagged(severity=2) │ Event: CompensationReviewPoolIncentivized(bountyWei) │ └─► External reviewers incentivized ``` ## 🔐 安全模型 ### 访问控制角色 | 角色 | 合约 | 权限范围 | |------|----------|--------------| | `DEFAULT_ADMIN_ROLE` | PulseConfig | 授予/撤销所有角色 | | `GOVERNANCE_ROLE` | PulseConfig | 配置 SLA、管理维护者 | | `PROVISIONER_ROLE` | PulseConfig | 接入新仓库 | | `TELEMETRY_TRANSMITTER_ROLE` | PRPulseTelemetry | 提交签名的遥测批次 | ### 安全特性 ✅ **EIP-191 签名验证** — 所有遥测批次必须由授权预言机签名 ✅ **重放保护** — 时序时间戳验证防止重复提交 ✅ **重入攻击防护** — 升级函数应用 OpenZeppelin ReentrancyGuard ✅ **顺序升级机制** — 防止直接滥用悬赏发放 ✅ **基于角色的访问控制** — 所有特权操作均采用 OpenZeppelin AccessControl ### 已知局限性 ⚠️ **预言机信任边界** — 被攻破的预言机密钥可提交虚假遥测数据 ⚠️ **咨询性悬赏** — 悬赏事件仅为信息提示，不会自动转账 ETH ⚠️ **时钟偏移风险** — 时间戳由预言机提供，非基于区块时间 **缓解策略：** - 使用多签名预言机池或阈值签名方案 - 实施链下监控与异常检测 - 对关键指标部署时间加权平均计算 ## 📚 文档 | 文档 | 描述 | |----------|-------------| | [架构](docs/architecture.md) | 合约拓扑与部署顺序 | | [遥测流水线](docs/telemetry-pipeline.md) | 数据摄取流程与编码参考 | | [升级引擎](docs/escalation-engine.md) | SLA 评估逻辑与升级规则 | | [安全模型](docs/security-model.md) | 访问控制、信任边界与局限性 | ## 🛠️ 开发工具 ### 监控与索引 - **Subgraph** — 历史遥测查询的 GraphQL API (`monitoring/subgraph/`) - **事件索引器** — 实时事件处理 (`monitoring/event-indexers/`) - **Grafana 仪表盘** — 可视化模板 (`monitoring/dashboards/`) ### 测试工具 - **模拟负载** — 示例遥测数据 (`helpers/mockPayloads/`) - **JSON Schema** — 验证模式 (`helpers/schemas/`) - **遥测生成器** — 合成数据生成 (`helpers/telemetryGenerator.js`) ## 🧪 测试 ### 测试覆盖率 ``` npm run coverage ``` | 合约 | 语句 | 分支 | 函数 | 行 | |----------|------------|----------|-----------|-------| | PulseConfig | 100% | 100% | 100% | 100% | | PRPulseTelemetry | 100% | 100% | 100% | 100% | | WorkflowEscalationEngine | 100% | 100% | 100% | 100% | ### 测试套件 - **PRPulseTelemetry.test.js** — 批次摄取、签名验证、重放保护 - **PulseConfig.test.js** — 仓库接入、SLA 配置、RBAC - **WorkflowEscalationEngine.test.js** — 阈值评估、升级推进 - **maliciousScenarios.test.js** — 攻击向量与边界情况 ## 🤝 参与贡献 欢迎贡献代码！请遵循以下准则： 1. Fork 本仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add amazing feature'`) 4. 推送至分支 (`git push origin feature/amazing-feature`) 5. 开启拉取请求 ### 代码规范 - 遵循 [Solidity 风格指南](https://docs.soliditylang.org/en/latest/style-guide.html) - 为所有新功能编写全面测试 - 保持 100% 测试覆盖率 - 提交前运行检查器：`npm run lint:sol` - 格式化代码：`npm run format:fix` ## 📄 许可证 本项目采用 **MIT 许可证** — 详情参见 [LICENSE](LICENSE) 文件。 ## 🙏 致谢 - **OpenZeppelin** — 经过实战检验的智能合约库 - **Hardhat** — 以太坊开发环境 - **以太坊社区** — 贡献 EIP-191 与签名标准 ## 📞 联系与支持 - **文档：** [docs/](docs/) - **问题追踪：** [GitHub Issues](https://github.com/your-org/pr-pulse-protocol/issues) - **讨论区：** [GitHub Discussions](https://github.com/your-org/pr-pulse-protocol/discussions)

标签：DAO, DevOps智能, EIP-191, Gas优化, GitHub集成, Hardhat, OpenZeppelin, Oracle, SLA强制执行, Solidity, Streamlit, 不可变数据, 区块链, 区块链工具, 去中心化, 去中心化Oracle, 去中心化自治组织, 可编程激励, 审计跟踪, 工作流优化, 工程团队, 数据验证, 智能合约, 智能合约安全, 激励机制, 瓶颈检测, 自动化运维, 访问控制, 重放保护