Contribute a definition, a proof, a fast implementation, a test, or a documentation change.
The roadmap describes the planned directions of the library. The
open issues include bugs, requested
features, and formalization tasks. Issues labeled good first issue or help wanted are suitable
starting points.
Start with README.md, the wiki, and the README.md file of
the subtree that you change. AGENTS.md gives the entry points and guardrails for AI
agents. If you do not know where to begin, open an issue or a discussion that describes your
interest.
Before you start a formalization or an optimization, search the open pull requests and issues for the same target:
gh pr list -R Verified-zkEVM/CompPoly --state open --search "<topic>"
gh issue list -R Verified-zkEVM/CompPoly --state open --search "<topic>"If an open PR covers the same declarations, ask its author whether the work is active. Do not duplicate active work. If you open a PR for the same target, link the earlier PR and explain how your work relates to it.
If earlier work appears abandoned, you may ask a maintainer whether to proceed. A maintainer may waive the overlap restriction for that contribution.
For a large contribution, such as a new polynomial representation or a new field family, we strongly encourage a blueprint before you write the Lean code. A blueprint describes these items:
- The contents of the formalization.
- The key definitions, theorems, and assumptions of the proposed Lean formalization.
- A dependency graph from the intermediate results to the final result.
- References to the relevant literature.
- Possible difficulties and design choices.
Open an issue or a discussion that proposes the contribution and its blueprint. Discuss the blueprint before you start a large implementation. A blueprint makes the structure of the work visible early, so that reviewers can comment before you invest in proofs.
For Python check prerequisites and commands, see Python tooling.
On a new clone, download the Mathlib build cache, and then build the library:
lake exe cache get
lake buildThe cache covers Mathlib and its dependencies. lake build compiles the CompPoly modules.
The build-cache page explains both caches. The writing checker in the
Writing section runs with uv.
Its commands select Python 3.12 and do not install a project package.
The quickstart is the canonical list of validation commands and their CI mapping. Run the commands for each type of change in your PR:
| Change | Commands |
|---|---|
| Any Lean change | lake build |
| Public API, proof refactor, or regression test | lake build and lake test |
Added, renamed, or deleted file under CompPoly/ |
./scripts/update-lib.sh, then ./scripts/check-imports.sh and lake build |
A sorry filled or added, or work that must stay axiom-clean |
lake build, then lake exe axiomsweep --check |
| Lean style cleanup or a large amount of new Lean code | ./scripts/lint-style.sh |
| Native field arithmetic or startup | The CompPolyNativeSmoke commands in tests/README.md |
| Benchmark | lake build CompPolyBench, then lake exe CompPolyBench --medium --validate-only |
| Documentation | uv run --no-project --python 3.12 python ./scripts/check-docs-integrity.py |
If CompPoly.lean changes, commit the regenerated file with the source changes. If you
intentionally add or close a sorry, refresh the axiom baseline with
lake exe axiomsweep --update-baseline and commit the diff. The axiom sweep never accepts
native-compiler trust in the baseline.
A faster version of a fast implementation is a welcome contribution. The
optimization loop gives the full protocol.
benchmarking.md explains how the suite measures.
benchmark-best-times.md gives the time to beat for each
row.
- Every function stays formally verified. Do not change the specification definition.
Connect a faster implementation to it in one of the two accepted forms. The first form is a
@[csimp]lemma with an equality theorem. The second form is a twin definition with an_eq_theorem that the call site depends on.@[implemented_by]substitutes code without a proof, so it is not accepted for this purpose.native_decideis forbidden everywhere, as the TCB policy states.lake exe axiomsweep --checkmust pass. - One change per PR. Give a PR one optimization with one measured effect, so that the verdict belongs to that change. Put two independent ideas in two PRs.
- The digest must not move. Benchmark inputs are seeded for each group, so the digest of a
group is the same across builds and commits. A
mismatchverdict means that the candidate computes a different result. The verdict shows a bug, not a measurement. - Test, then measure, then prove. The proof is the expensive part, so do it last. Prove only a
change that tests show correct on concrete inputs and that measurement shows faster. If the
implementation has no tests of its own under
tests/, add them first. Make sure that the original, formally verified function passes them before you change anything. These tests are then the test step of every iteration. - Add a test for each bug that the proof finds. If the proof finds a bug that the tests did not
catch, add a test for that bug. While you explore, the refinement theorem can contain a
sorry, so that the tests and the timings use the new code. A PR never contains thatsorry. Uselake exe axiomsweep --checkto confirm that none remains. lake testis part of the gate, as well aslake build. An implementation is not faster if its tests take hours to elaborate. In this repository, inlining attributes on loop-shaped bodies caused that problem.- Write the proof so that the next optimization does not break it. State the coefficient and
unfolding facts of the implementation as named lemmas marked
@[simp]or@[grind =]. Close the refinement theorem withsimp only [...]over these lemmas or withgrind, not with a hand-writtenrwchain. The next change to the implementation then changes lemmas, not proof steps. See Proving so the proof survives the next iteration. - Quote ratios, not nanoseconds. Numbers from your machine are not comparable with the tables in
benchmark-best-times.md, which come from one reference machine. Report the A/B verdict and the candidate-over-baseline ratio for each row. The tables and pass log use measurements from that reference machine. Do not edit them in your PR. - Keep the harness out of it. Do not change
bench/and a fast implementation in the same PR. Both sides of the comparison would change, so a reviewer cannot judge the result. If you need a new benchmark group, add it first in its own PR. Follow Adding a benchmark.
lake build CompPolyBenchLib CompPolyBench # `lake build` alone does not build bench/
lake exe CompPolyBench --list # every group key
lake exe CompPolyBench --medium --validate-only --groups <key> # correctness only, no timings
lake exe CompPolyBench --medium --groups <key> # timed; output under bench/out/CI, the A/B loop, and the best-times tables use the --medium preset. The results, a Markdown
report, and a manifest go to bench/out/, which git ignores. Read the Spread column before the
number. A row with n=1 has no dispersion, so do not read a ratio from it.
./scripts/bench-ab.sh freeze # build the baseline binary from the current tree
# edit the fast implementation (a `sorry` on its refinement theorem is fine here)
lake build && lake test # test: the implementation's tests and the digest gate
./scripts/bench-ab.sh run <key>[,<key>...] # measure: both binaries turn about, then --compare
# on `faster` without SUSPECT: prove the refinement theorem, then
lake build && lake test && lake exe axiomsweep --checkFreeze the baseline from main before you edit. The run command builds the candidate once and
runs the two binaries alternately. It adds the harness groups to measure machine drift, and it
prints the comparison. A copy of the comparison goes to bench/out/ab/<run>/compare-*.md.
A row is faster only when two conditions are true. The ratio of medians must clear the threshold,
which is 5% by default. Every candidate invocation must also beat every baseline invocation.
If the harness drift is outside ±10%, repeat the run instead of reading it. Otherwise, keep the
change on a faster verdict without SUSPECT, and revert it on any other verdict. Use a quiet
machine. Do not rebuild or edit bench/ while a run is in progress.
- The title
perf(<scope>): <subject>. - The change in one paragraph: what was slow, the reason, and what the new code does.
- The proof: the
@[csimp]or_eq_theorem that connects the new code to the specification. Name it in the description. Close it over the lemma set of the implementation, not with a rewrite chain. - The tests: the concrete-input tests for the implementation. Add them in this PR if the implementation had none.
- The A/B evidence: the
compare-*.mdtable or its relevant rows, with the preset, the rounds, and the drift line. If you keep asameorslowerverdict for a different reason, such as a compile-time fix or a correctness repair, give that reason. - A statement that
lake build,lake test,--validate-onlyon the affected groups, andlake exe axiomsweep --checkpass.
A new field carrier or polynomial representation becomes a protocol type as soon as ArkLib can
name it. Add its serialization in the same PR. serialization.md
gives the formats and the invariants that they keep. Its "Adding an instance" section is the
procedure. The PR must contain these items:
- The codec. A fixed-width scalar, such as a prime-field carrier or a binary field, gets
CanonicalNatandByteCodec := ByteCodec.ofCanonicalNat _. A fixed-length composite, such as an extension or a dense coefficient vector, getsByteCodecby concatenation, usually throughByteCodec.instVector. A variable-length type getsDelimitedCodec. Build it from the list, pair, and vector codecs, withValidstating what fits theu64framing. - The theorems through the class interfaces, not only through the raw functions. These theorems
are
deserialize (serialize x) = some x, injectivity, and, for a scalar, the round trip of the total decoder (CanonicalNat.deserialize_serialize). The derived instances give the first two when you prove the one law of the codec. - For a fast carrier of an existing field, the agreement lemma with the specification field,
toBytes (ofField x) = toBytes x. Add a test that the stored word is not the emitted value. The agreement lemma is the correctness statement of the instance. It keeps the bytes independent of the carrier. - A
Bytes.leantest module that mirrors the source module. It contains a known byte vector, a round trip throughserializeanddeserialize, and one rejected input. - A
Reprinstance if the type has none. It is not part of the byte format, but a type that can be written out should also be printable.
Do not add ToJson, FromJson, or a different ad hoc encoding. If a consumer needs JSON, it will
be hex strings of these same bytes.
Use this format:
<type>(<optional-scope>): <subject>
Types:
feat: A feature or formalized resultfix: A defect correctiondoc: Documentationdocs: Documentation, as an alternative todocstyle: Formattingrefactor: A change to the organization or interfacestest: Testschore: Maintenanceperf: A performance improvementci: CI workflows and checks
Subject:
- Name the change with an imperative phrase, such as "add the coset NTT", or with a noun phrase for the result, such as "the additive NTT over a coset". Do not use "changed" or "changes".
- Start with a lowercase letter. Keep the capitalization of a name or identifier, such as
NTT. - Do not end the subject with a period.
- Use the scope when it helps identify the affected component, such as
fieldsorbench.
For a breaking change, put ! before the colon, as in
refactor(univariate)!: rename the evaluation API. The PR summary workflow adds a warning to its
summary when a title does not follow this format.
Keep the description proportional to the change. Give the reader the information needed to assess the contribution:
- The problem, the change, and its purpose.
- How the change differs from the previous behavior.
- The headline declarations, with their hypotheses when a reader needs them to judge the claim.
- The
sorryadmissions that the PR adds or closes, and any change toscripts/axiom_baseline.json. - The validation commands that you ran and their results. Identify checks that you did not run.
- Renamed or removed declarations and the affected callers.
- Related issues, such as
Closes #123, and overlapping PRs.
Keep the claims in the title and the description consistent with the code and the evidence.
A successful build does not show that a statement is correct or that a fast implementation is
faster. If the PR changes commands, repository structure, generated outputs, or recurring
contributor guidance, update the matching page in docs/wiki/ in the same
PR.
Give each PR one topic. Separate mechanical changes from mathematical changes when each can be reviewed and validated independently.
Use a stack of PRs when a contribution needs several dependent PRs. Each PR must build against its
stated base. Name that base in the description. The import check in check_imports.yml runs only
on PRs that target main, so run ./scripts/check-imports.sh yourself for a PR in a stack.
CompPoly permits squash and rebase merges. It does not permit merge commits.
The writing guide offers advice for documentation, docstrings, comments, commit messages, PR and issue text, and review comments. Use it to improve clarity and precision. Leave clear, correct text alone, even if it does not follow a rule or the checker reports it. The contribution requirements in this document retain their stated force.
Use the writing workflow when you draft or revise that text. Keep claims, hypotheses, uncertainty, trust statements, and requirement strength unchanged during a style edit. The vocabulary records technical meanings. It does not prohibit other meanings when their context is clear.
The writing checker gives optional wording suggestions. It does not establish clarity, accuracy or STE conformance. You can run it on changed prose or a draft PR description:
uv run --no-project --python 3.12 python scripts/check-writing.py --base origin/main
uv run --no-project --python 3.12 python scripts/check-writing.py --stdin description < description.mdThe Writing workflow runs the same check on each PR and reports its findings as warnings. These
warnings do not fail the build. Read findings in context. Correct claim and source errors, and
use style suggestions when they improve clarity.
Follow the Lean community's contribution guidelines. The linting script enforces some of them.
- Files:
UpperCamelCase.lean(for example,BinarySearch.lean). - Types and Structures:
UpperCamelCase(for example,MonoidHom,Visualizer). - Functions and Terms:
lowerCamelCase(for example,binarySearch,isPrime). - Theorems and Proofs:
snake_case(for example,add_comm,list_reverse_id). - Acronyms: Treat an acronym as a word (for example,
HtmlParser, notHTMLParser). - Prop-valued Classes: Use
UpperCamelCase. If the class is an adjective, use theIsprefix (for example,IsCompact,IsPrime). If it is a noun, use no prefix (for example,Group,TopologicalSpace). - Spelling: Use American English for declaration names (for example,
analyze, notanalyse, andcolor, notcolour). - Dot Notation: Use namespaces to group related definitions (for example,
List.map). Namespaces enable dot notation (for example,l.map f) when the type is known. Use manual dot notation for logical connectives and equality (for example,And.intro,Eq.refl,Iff.mp). Preferred but not enforced. The merged code uses bothh.symmandEq.symm h. Flag a use only when it is ambiguous. - Axiomatic Names: Use the standard names for properties:
refl,symm,trans,comm,assoc,inj(injective), andcongr. - Identifiers:
- Use namespaces for logical properties (for example,
And.comm,Or.intro). - Use descriptive names for arithmetic and algebraic properties (for example,
mul_comm,add_assoc).
- Use namespaces for logical properties (for example,
- Hypotheses: Use
_of_to separate hypotheses, in the order in which they occur. For example,lt_of_succ_lemeans "less than follows from successor less equal". - Variants: Use
leftorrightto describe which argument changes or is relevant (for example,add_le_add_left). - Structural Lemmas:
ext: For extensionality (∀ x, f x = g x → f = g).iff: For bidirectional implications.inj/injective: For injectivity results.mono/antitone: For monotonicity.
- Induction and Recursion:
induction_on/recOn: Use when the value comes before the constructions (the motive eliminates toProporType).induction/rec: Use when the constructions come before the value.
- Predicates: Usually use prefixes (for example,
isClosed_Icc, notIcc_isClosed). Property suffixes such as_inj,_mono,_injective, and_surjectiveare exceptions.
- Theorem-only helper modules: Prefer the name
Lemmasfor a new theorem-only leaf module. - Proof placement: Keep transport and equivalence lemmas near the bridge layer, such as
ToPolyorMvPolyEquiv. Keep the first user-facing correctness theorem next to the definition that it justifies. For example, the bridge lemmas inCompPoly/Univariate/ToPoly/Core.leanandCompPoly/Multivariate/MvPolyEquiv/Eval.leanstay with the bridge. A theorem such aseval_interpolatePow_at_nodestays withinterpolatePowinCompPoly/Univariate/Lagrange.lean.
We follow the Mathlib style, adapted for algebraic code. The conventions below agree with the use
across the repository (Univariate/, Multivariate/, Multilinear/, Bivariate/, Fields/).
If you are not sure, read the adjacent files.
u,v,w, ... : Universesα,β,γ, ... : Generic types (in non-algebraic contexts)R,M,G,F, ... : Algebraic carrier types (rings, modules, groups, fields). Prefer these names toαandβin algebraic declarations such asvariable {R : Type*} [Semiring R]a,b,c, ... : Propositionsx,y,z, ... : Elements of a generic typeh,h₁, ... : Assumptions and hypothesesp,q: Polynomials or predicates. The type and the context tell them apart. In this repository,pandqare usuallyCPolynomial,CMvPolynomial, orCMlPolynomialvaluesm,n,k, ... : Natural numbersi,j,k, ... : Indices into vectors, lists, orFin n. They can beℕ-valued orℤ-valued. The convention describes the indexing role, not the underlying types,t, ... : Sets or lists
When we translate theorem statements into names, we use these standard mappings for symbols:
Logic
| Symbol | Name | Symbol | Name | Symbol | Name |
|---|---|---|---|---|---|
∨ |
or |
∧ |
and |
¬ |
not |
→ |
of / imp |
↔ |
iff |
∃ |
exists |
∀ |
all / forall |
= |
eq |
≠ |
ne |
Sets and Lattices
| Symbol | Name | Symbol | Name | Symbol | Name |
|---|---|---|---|---|---|
∈ |
mem |
∉ |
notMem |
⊆ |
subset |
∩ |
inter |
∪ |
union |
\ |
sdiff |
≤ |
le |
< |
lt |
⊥ |
bot |
⊤ |
top |
⊔ |
sup |
⊓ |
inf |
Algebra
| Symbol | Name | Symbol | Name | Symbol | Name |
|---|---|---|---|---|---|
+ |
add |
* |
mul |
^ |
pow |
- |
neg / sub |
⁻¹ |
inv |
/ |
div |
∑ |
sum |
∏ |
prod |
• |
smul |
As in Mathlib, use ≤ (le) and < (lt) in theorem statements. Use ≥ (ge) or > (gt)
only when the argument order makes them necessary.
- Line Length: Keep
.leansource lines under 100 characters. The rule does not apply to Markdown, CI, or workflow files, because the enforced linterscripts/lint-style.pyprocesses only.leanfiles. - Indentation: Use 2 spaces for indentation.
- Headers: Start each file with the copyright, license, and authors block. Do not add a
separate AI-attribution line. List only the credited authors on the
Authors:line. Then follow the module-system shape thatmodule-system.mddescribes:/- Copyright (c) 2026 CompPoly Contributors. All rights reserved. Released under Apache 2.0 license as described in the file LICENSE. Authors: Author Name -/ module public import CompPoly.Data.Array.Lemmas /-! # Module docstring -/ public section
- Imports: Group the imports at the top of the file.
- Operators: Put spaces on both sides of
:,:=, and infix operators. Put an operator before a line break, not at the start of the next line. - Hypotheses: Prefer hypotheses to the left of the colon (for example,
(h : P) : Q), not in arrows (: P → Q), when the proof introduces them. - Functions: Prefer
fun x ↦ ...toλ x, .... - Instances: Use the
wheresyntax to define instances and structures. Preferred but not enforced. The merged code uses bothinstance ... := ⟨...⟩andinstance ... where. - Binders: Put a space after a binder (for example,
∀ x,, not∀x,). - Tactic Mode: Put
byat the end of the line before the tactic block. Indent the tactic block. - Calculations: Align the relations in a
calcblock. - Empty Lines: Do not put empty lines inside definitions or proofs.
- Delimiters: Avoid parentheses where possible. Use
<|(pipe left) and|>(pipe right) to reduce nesting. Do not use;to separate tactics, except in short, single-line tactic sequences. The<|and|>preference is preferred but not enforced. The merged code uses both styles. The;guidance still applies. - Error Messages: In a custom error or trace message, put interpolated data in backticks (inline) or on a new indented line.
We aim for consistent representations of equivalent statements:
- Standard Forms: Use established normal forms (for example,
s.Nonemptyinstead ofs ≠ ∅). They enable dot notation and keep statements consistent. - Inequalities with Bottom and Top:
- In assumptions, use
x ≠ ⊥, which is easier to check. - In conclusions, use
⊥ < x, which gives a stronger result. - Use the same forms for top:
x ≠ ⊤in assumptions andx < ⊤in conclusions.
- In assumptions, use
- Squeezing Simp: Do not "squeeze" a terminal
simpcall intosimp only [...]unless performance or stability makes it necessary. An unsqueezedsimpis often easier to read, and small library changes break it less often. - Comments: Use
--for inline comments and/- ... -/for block comments.
- Definitions (
def): By default,defcreates asemireducibledefinition. Tactics such asrwandsimpusually do not unfold it without an explicit instruction. Preferdeffor most definitions, because it keeps terms manageable. - Abbreviations (
abbrev):abbrevcreates areducibledefinition that is always unfolded. Use it for type synonyms or light aliases whose underlying term should stay visible. - Irreducible: Use
irreducible(or astructurewrapper) to seal an API boundary when the internal implementation details should not leak.
- Renaming: When you rename a declaration, fix the breakage that the rename causes. If you
cannot fix it, for example in downstream code, keep the old name as a deprecated alias:
@[deprecated (since := "YYYY-MM-DD")] alias oldName := newName
- Removal: When you remove a declaration, give a message that explains the transition:
@[deprecated "Use `better_theorem` instead" (since := "YYYY-MM-DD")] theorem old_theorem ...
Every definition and major theorem should have a docstring. Write docstrings and comments to the writing standard.
- Module Docstrings: Each file should start with a
/-! ... -/block that contains a title, a summary, the notation, and the references. - Sectioning Comments: Use
/-! ### Title -/to divide a large file into sections. These comments appear in the generated documentation. - Declaration Docstrings: Put a
/-- ... -/docstring above each definition. State the meaning of the object or the claim of the theorem, with the relevant hypotheses. - Trust Statements: In a certificate or checker docstring, name the checker, the checked data, and the components that stay trusted. Rule C9 of the writing standard gives the details.
- Syntax:
- Use backticks for Lean names:
`List.map`. - Use LaTeX for mathematics:
$ f(x) = y $(inline) or$$ \sum_{i=0}^n i $$(display).
- Use backticks for Lean names:
- Tactic Documentation: Give each tactic a complete, self-contained description.
When you cite a paper in a Lean docstring, follow these conventions:
-
Use citation keys in text: Cite a paper with a key such as
[ACFY24], not with its full title or URL. -
Include a References section: Each file that cites papers should have a
## Referencessection in its module docstring:## References * [Arnon, G., Chiesa, A., Fenzi, G., and Yogev, E., *WHIR: Reed–Solomon Proximity Testing with Super-Fast Verification*][ACFY24] * [Ben-Sasson, E., Carmon, D., Ishai, Y., Kopparty, S., and Saraf, S., *Proximity Gaps for Reed-Solomon Codes*][BCIKS20]Use the format
* [Author Last Name, First Initial, *Title*][citation_key]. -
Add BibTeX entries: Give each academic paper an entry in
blueprint/src/references.bib. When you add a paper, add the BibTeX entry, use the citation key in your Lean file, and list the paper in the References section. The file is a standalone bibliography, and the repository has no rendered leanblueprint project. Its header gives thegrepcommand that lists cited keys without an entry. -
Non-academic references: An implementation reference, such as a GitHub repository or a specification, can give its URL directly. It usually does not need a BibTeX entry.
CompPoly follows the principles of the Mathlib Code of Conduct.
Project participation includes contributions, issues, and discussions. Participants agree to the code of conduct. Treat other contributors with respect. You can report unacceptable behavior to the project maintainers.
Like many other Lean projects, CompPoly is licensed under the terms of the Apache License 2.0. The full license text is in the LICENSE file.
See NOTICE for upstream attribution and source file headers for file-specific copyright and author credits.
By contributing to CompPoly, you agree that your contributions will be licensed under this same license. Ensure you are comfortable with these terms before submitting contributions.