Repository files navigation

Plonky3 is a toolkit for implementing polynomial IOPs (PIOPs), such as PLONK and STARKs. It aims to support several polynomial commitment schemes, such as Brakedown.

This is the "core" repo, but the plan is to move each crate into its own repo once APIs stabilize.

Fields:

• Mersenne31
  • "complex" extension field
  • ~128 bit extension field
  • AVX2
  • AVX-512
  • NEON
• BabyBear
  • ~128 bit extension field
  • AVX2
  • AVX-512
  • NEON
• Goldilocks
  • ~128 bit extension field

Generalized vector commitment schemes

• generalized Merkle tree

Polynomial commitment schemes

• FRI-based PCS
• tensor PCS
• univariate-to-multivariate adapter
• multivariate-to-univariate adapter

PIOPs

• univariate STARK
• multivariate STARK
• PLONK

Codes

• Brakedown
• Reed-Solomon

Interpolation

• Barycentric interpolation
• radix-2 DIT FFT
• radix-2 Bowers FFT
• four-step FFT
• Mersenne circle group FFT

Hashes

• Rescue
• Poseidon
• Poseidon2
• BLAKE3
  • modifications to tune BLAKE3 for hashing small leaves
• Keccak-256
• Monolith

Many variations are possible, with different fields, hashes and so forth, but here are a couple examples of Plonky3 benchmarks.

Prove 2^19 Poseidon2 permutations of width 16, using theKoalaBear field and Keccak in the Merkle tree:Poseidon2

RUSTFLAGS="-Ctarget-cpu=native" cargo run --example prove_poseidon2_koala_bear_keccak --release --features parallel

Prove 1365 Keccak-f permutations, using theBabyBear field and Keccak in the Merkle tree.

RUSTFLAGS="-Ctarget-cpu=native" cargo run --example prove_baby_bear_keccak --release --features parallel

Addinglto = "fat" in the top-level Cargo.toml may give some additional speedup, at the cost of longer compilation times.

Plonky3 contains optimizations that rely on newer CPU instructions that are not available in older processors. These instruction sets include x86'sBMI1 and 2,AVX2, andAVX-512. Rustc does not emit those instructions by default; they must be explicitly enabled through thetarget-feature compiler option (or implicitly by settingtarget-cpu). To enable all features that are supported on your machine, you can settarget-cpu tonative. For example, to run the tests:

RUSTFLAGS="-Ctarget-cpu=native" cargo test

Support for some instructions, such as AVX-512, is still experimental. They are only available in the nightly build of Rustc and are enabled by thenightly-features feature flag. To use them, you must enable the flag in Rustc (e.g. by settingtarget-feature) and you must also enable thenightly-features feature.

Some optimizations (in particular, AVX-512-optimized math) rely on features that are currently available only in the nightly build of Rustc. To use them, you need to enable thenightly-features feature. For example, to run the tests:

cargo test --features nightly-features

The verifier might panic upon receiving certain invalid proofs.

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.

Do you feel keen and able to help with Plonky3? That's great! Weencourage external contributions!

We want to make it easy for you to contribute, but at the same time wemust manage the burden of reviewing external contributions. We are asmall team, and the time we spend reviewing external contributions istime we are not developing ourselves.

We also want to help you to avoid inadvertently duplicating work thatis already underway, or building something that we will notwant to incorporate.

First and foremost, please keep in mind that this is a highlytechnical piece of software and contributing is only suitable forexperienced mathematicians, cryptographers and software engineers.

The Polygon Zero Team reserves the right to accept or reject anyexternal contribution for any reason, including a simple lack of timeto maintain it (now or in the future); we may even decline to reviewsomething that is not considered a sufficiently high priority for us.

To avoid disappointment, please communicate your intention tocontribute openly, while respecting the limited time and availabilitywe have to review and provide guidance for external contributions. Itis a good idea to drop a note in our public Discord #developmentchannel of your intention to work on something, whether an issue, anew feature, or a performance improvement. This is probably all that'sreally required to avoid duplication of work with other contributors.

What follows are some more specific requests for how to write PRs in away that will make them easy for us to review. Deviating from theseguidelines may result in your PR being rejected, ignored or forgotten.

Obviously PRs will not be considered unless they pass our GithubCI. The Github CI is not executed for PRs from forks, but you cansimulate the Github CI by running the commands in.github/workflows/ci.yml.

Under no circumstances should a single PR mix different purposes: YourPR is either a bug fix, a new feature, or a performance improvement,never a combination. Nor should you include, for example, twounrelated performance improvements in one PR. Please just submitseparate PRs. The goal is to make reviewing your PR as simple aspossible, and you should be thinking about how to compose the PR tominimise the burden on the reviewer.

Plonky3 uses stable Rust, so any PR that depends on unstable featuresis likely to be rejected. It's possible that we may relax this policyin the future, but we aim to minimize the use of unstable features;please discuss with us before enabling any.

Here are a few specific guidelines for the three main categories ofPRs that we expect:

In the PR description, please clearly but briefly describe

1. the bug (could be a reference to a GH issue; if it is from adiscussion (on Discord/email/etc. for example), please copy in therelevant parts of the discussion);
2. what turned out to the cause the bug; and
3. how the PR fixes the bug.

Wherever possible, PRs that fix bugs should include additional teststhat (i) trigger the original bug and (ii) pass after applying the PR.

If you plan to contribute an implementation of a new feature, pleasedouble-check with the Polygon Zero team that it is a sufficientpriority for us that it will be reviewed and integrated.

In the PR description, please clearly but briefly describe

1. what the feature does
2. the approach taken to implement it

All PRs for new features must include a suitable test suite.

Performance improvements are particularly welcome! Please note that itcan be quite difficult to establish true improvements for theworkloads we care about. To help filter out false positives, the PRdescription for a performance improvement must clearly identify

1. the target bottleneck (only one per PR to avoid confusing things!)
2. how performance is measured
3. characteristics of the machine used (CPU, OS, #threads if appropriate)
4. performance before and after the PR

Unless you explicitly state otherwise, any contribution intentionallysubmitted for inclusion in the work by you, as defined in theApache-2.0 license, shall be dual licensed as above, without anyadditional terms or conditions.