Plonky3代码贡献指南：从新手到核心开发者的成长路径

【免费下载链接】Plonky3A toolkit for polynomial IOPs (PIOPs)项目地址: https://gitcode.com/gh_mirrors/pl/Plonky3

Plonky3是一个用于实现多项式IOP（PIOP）的工具包，主要用于支持STARK-based的零知识虚拟机。作为一名开源项目，Plonky3欢迎来自全球开发者的贡献，但需要遵循一定的规范和流程。本指南将详细介绍如何从新手逐步成长为Plonky3的核心开发者。

🚀 准备工作：搭建开发环境

在开始贡献代码之前，您需要正确配置开发环境。Plonky3使用Rust语言编写，因此需要安装Rust工具链：

# 克隆Plonky3仓库 git clone https://gitcode.com/gh_mirrors/pl/Plonky3 cd Plonky3 # 安装Rust（如果尚未安装） curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 设置环境变量以启用CPU优化 export RUSTFLAGS="-Ctarget-cpu=native"

为了获得最佳性能，建议启用所有支持的CPU特性。Plonky3包含针对新CPU指令集的优化，如x86的BMI1/2、AVX2和AVX-512指令集。

📚 理解项目架构

Plonky3采用模块化设计，包含多个独立的crate。每个crate都有特定的功能：

• 字段模块：提供多种有限域实现，包括Mersenne31、BabyBear、KoalaBear和Goldilocks
• 承诺方案：包含FRI-based多项式承诺方案和广义Merkle树
• 哈希函数：支持Rescue、Poseidon、Poseidon2、BLAKE3、Keccak-256、SHA-256和Monolith
• STARK实现：提供单变量和多变量STARK实现
• FFT算法：包含多种快速傅里叶变换实现

项目的主要入口点位于Cargo.toml，它定义了工作空间中的所有成员crate。每个crate都有独立的版本管理和依赖关系。

🔍 寻找贡献机会

1. 从简单问题开始

对于新手贡献者，建议从以下类型的任务开始：

• 修复文档错误
• 添加测试用例
• 优化现有代码的性能
• 修复已知的bug

2. 查看现有问题

在开始编码之前，建议先查看项目的issue列表，了解当前的需求和待解决的问题。这可以避免重复工作，并确保您的贡献符合项目优先级。

3. 与社区沟通

Plonky3团队建议在开始任何重要工作之前，先在公共Discord的#development频道中说明您的意图。这样可以：

• 避免与其他贡献者的工作重复
• 获得团队对实现方案的反馈
• 确保您的贡献符合项目发展方向

📝 代码贡献流程

第一步：创建分支

git checkout -b feature/your-feature-name

第二步：实现功能或修复bug

在编写代码时，请遵循以下规范：

1. 代码风格：遵循Rust 2018惯用语法，使用cargo fmt格式化代码
2. 测试覆盖：为所有新功能添加测试用例
3. 性能考虑：对于性能优化，需要提供基准测试数据
4. 文档完善：为公共API添加文档注释

第三步：运行测试

在提交PR之前，确保所有测试通过：

# 运行所有测试 RUSTFLAGS="-Ctarget-cpu=native" cargo test # 运行CI工作流中的命令 cargo check --all-targets cargo test --all-targets cargo clippy --all-targets -- -D warnings

第四步：提交Pull Request

创建PR时，请确保：

1. PR描述清晰：详细说明解决的问题或实现的功能
2. 单一目的：每个PR只解决一个问题（bug修复、新功能或性能优化）
3. 包含测试：所有PR必须包含相应的测试用例
4. 性能数据：对于性能优化，需要提供前后对比数据

🎯 不同类型的贡献指南

1. Bug修复贡献

如果您要修复一个bug，请在PR描述中明确说明：

• bug的具体表现和复现步骤
• bug的根本原因分析
• 您的修复方案和原理

例如，如果修复验证器在某些恶意证明下可能panic的问题，您需要：

• 添加触发该bug的测试用例
• 在修复后确保测试通过
• 考虑使用catch_unwind包装验证逻辑

2. 新功能贡献

在实现新功能之前，请务必与Polygon Zero团队确认该功能的优先级。新功能PR必须包含：

• 功能描述和使用场景
• 实现方案的技术细节
• 完整的测试套件
• 必要的文档更新

3. 性能优化贡献

性能优化是Plonky3特别欢迎的贡献类型。提交性能优化PR时，必须提供：

• 目标瓶颈的具体描述
• 性能测试方法和环境信息
• 优化前后的性能对比数据
• 机器配置（CPU、操作系统、线程数等）

🔧 开发最佳实践

1. 使用正确的RUSTFLAGS

为了获得最佳性能，始终设置：

export RUSTFLAGS="-Ctarget-cpu=native"

2. 启用并行处理

对于计算密集型任务，启用parallel特性：

cargo build --features parallel

3. 内存优化

对于重复证明的工作负载，可以设置jemalloc配置：

export JEMALLOC_SYS_WITH_MALLOC_CONF="retain:true,dirty_decay_ms:-1,muzzy_decay_ms:-1"

4. 链接时优化

在发布构建中启用LTO以获得额外性能提升：

[profile.release] lto = "fat"

🧪 测试策略

Plonky3的测试分为多个层次：

1. 单元测试：每个crate内部的测试
2. 集成测试：跨crate的功能测试
3. 性能测试：使用criterion进行基准测试
4. 示例测试：确保示例代码正常工作

运行特定模块的测试：

# 测试特定crate cargo test -p p3-field # 运行性能基准测试 cargo bench

📊 性能基准测试

Plonky3包含详细的性能基准测试。运行示例基准测试：

RUSTFLAGS="-Ctarget-cpu=native" cargo run --example prove_prime_field_31 --release --features parallel -- --field koala-bear --objective poseidon-2-permutations --log-trace-length 17 --discrete-fourier-transform radix-2-dit-parallel --merkle-hash keccak-f

这个命令会证明2^20个宽度为16的Poseidon2置换，使用KoalaBear字段、Radix2DitParallel DFT和KeccakF作为Merkle树哈希。

🚨 常见陷阱和注意事项

1. 避免混合不同类型的修改

• 不要在一个PR中混合bug修复和新功能
• 不要在一个PR中包含多个不相关的性能优化
• 保持PR的单一目的性，便于评审

2. 文档修改限制

Plonky3团队通常不接受仅包含文档小修改的PR。如果发现文档问题，建议创建issue，团队会在有时间时修复。

3. 使用稳定版Rust

Plonky3使用稳定版Rust，避免依赖不稳定特性。如果需要使用不稳定特性，请先与团队讨论。

4. CI要求

所有PR必须通过GitHub CI检查。您可以在本地运行CI命令来预检查：

# 模拟CI检查 cargo check --all-targets cargo test --all-targets cargo clippy --all-targets -- -D warnings

🏆 成为核心开发者

随着贡献的增加，您可能希望成为Plonky3的核心开发者。以下是成长路径：

阶段一：熟悉项目

• 阅读所有主要模块的源代码
• 理解Plonky3的架构设计
• 运行并分析所有示例程序

阶段二：贡献修复

• 修复简单的bug
• 添加测试用例
• 改进文档

阶段三：实现功能

• 实现较小的新功能
• 进行性能优化
• 添加新的示例

阶段四：架构设计

• 参与新功能的架构设计
• 评审其他贡献者的PR
• 帮助维护项目质量

阶段五：核心维护

• 拥有合并PR的权限
• 参与项目路线图规划
• 指导新贡献者

📞 获取帮助和支持

1. 社区资源

• Telegram群组：t.me/plonky3
• GitHub仓库的问题和讨论区
• 项目文档和示例代码

2. 学习资源

• 阅读field/README.md了解字段实现
• 查看circle/README.md学习循环群FFT
• 参考examples/examples/prove_prime_field_31.rs学习使用示例

3. 调试技巧

• 使用tracing进行日志记录
• 启用调试符号进行性能分析
• 使用criterion进行基准测试

🎉 开始您的贡献之旅

现在您已经了解了Plonky3代码贡献的完整流程。无论您是密码学专家、数学爱好者还是系统程序员，Plonky3都欢迎您的贡献。从简单的bug修复开始，逐步深入了解这个强大的多项式IOP工具包。

记住，每个伟大的开源项目都是由像您这样的贡献者共同构建的。您的每一行代码、每一个测试、每一次优化，都在让Plonky3变得更加强大和可靠。

开始您的第一个贡献吧！🚀

【免费下载链接】Plonky3A toolkit for polynomial IOPs (PIOPs)项目地址: https://gitcode.com/gh_mirrors/pl/Plonky3