audit: tentative scoping document

[mratsim]

This is a tentative scoping document for Constantine's audit.

cc-ing interested parties:

Ethereum Foundation: @JustinDrake, @asanso, @jtraglia, @kevaundray
Consensus Client teams: @arnetheduck, @tersec, @OisinKyne, @sauliusgrigaitis,
Execution Client teams: @arnetheduck, @tersec, @garyschulte, @NickSneo

I've also created a discussion thread to use once scoping is done #482

[greptile-apps]

Greptile Summary

This PR adds a new audit/scoping.md document that proposes an audit scope for the Constantine cryptography library, targeting interested parties from the Ethereum Foundation and various client teams. It inventories the library's structure, external dependencies, cryptographic components in scope (KZG, BLS signatures, EVM precompiles), and out-of-scope items, and cross-references prior audits of comparable libraries (BLST, gnark, MCL).

Key observations from the review:

• Typo — "thread" vs. "threat" (line 52): In the Dependencies section, "To remove the thread of supply chain attacks" should read "threat." This is particularly noticeable in a security-focused audit document.
• Typo — "examplified" (line 10): Should be "exemplified."
• "Respectively" ordering mismatch (lines 22–25): The prose lists APIs as "C, Go and Rust" but the bulleted links follow C → Rust → Go order, making the "respectively" incorrect.
• Unresolved TODO (line 17): _TODO: tag a new version for audit_ remains in the document, which should be resolved before sharing with auditors.
• Missing trailing newline (line 229): The file ends without a newline.

Confidence Score: 5/5

• This PR is safe to merge — it is documentation-only with no code changes.
• The change is a single new Markdown file with no code logic. All issues found are minor textual errors (typos, ordering, a TODO note, and a missing newline) that do not affect any library functionality. Safe to merge once the prose is polished.
• No files require special attention; all issues are editorial in nature.

Important Files Changed

Filename	Overview
audit/scoping.md	New audit scoping document describing Constantine's library structure, dependencies, and cryptographic scope for both Consensus and Execution layers. Contains a few typos ("examplified", "thread" instead of "threat"), a "respectively" ordering mismatch between the prose and list (C/Go/Rust vs C/Rust/Go), an unresolved TODO for tagging an audit version, and a missing trailing newline.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Constantine Library] --> B[High-level Protocols\nconstantine/]
    A --> C[C API\ninclude/]
    A --> D[Go API\nconstantine-go/]
    A --> E[Rust API\nconstantine-rust/]

    B --> CL[Consensus Layer]
    B --> EL[Execution Layer]

    CL --> KZG[KZG Polynomial Commitments\nEIP-4844]
    CL --> BLS[BLS Signatures\nBLS12-381]
    CL --> EIP2333[EIP-2333 Key Derivation]

    EL --> PRE[EVM Precompiles]
    EL --> VKL[Verkle IPA\nin scope?]

    PRE --> SHA[SHA-256]
    PRE --> MODEXP[Modular Exponentiation]
    PRE --> BN254[BN254 add/mul/pairing]
    PRE --> BLS381[BLS12-381 ops\nnext upgrade]

    A --> MATH[Math Layer]
    MATH --> ARITH[Bigint & Field Arithmetic]
    MATH --> EXT[Extension Fields]
    MATH --> EC[Elliptic Curves]
    MATH --> PAIR[Pairings]
    MATH --> H2C[Hash to Curve]
    MATH --> POLY[Polynomial Arithmetic]
    MATH --> ENDO[Endomorphisms]

    A --> MISC[Misc]
    MISC --> HASH[SHA-256 / HMAC / HKDF]
    MISC --> RNG[CSPRNG]
    MISC --> TP[Threadpool]

Loading

_{Last reviewed commit: b88ba53}

[greptile-apps]

"thread" should be "threat"

The word "thread" is used where "threat" is clearly intended. In the context of a security-focused audit document, this creates a confusing sentence.

Suggested change

	To remove the thread of supply chain attacks, Constantine has no external dependencies except:
	To remove the threat of supply chain attacks, Constantine has no external dependencies except:

[greptile-apps]

Typo: "examplified" → "exemplified"

Suggested change

	This is examplified by investing in 5 different clients for the Consensus Layer (CL).
	This is exemplified by investing in 5 different clients for the Consensus Layer (CL).

[greptile-apps]

"respectively" order mismatch

The text states "C, Go and Rust API are exposed respectively in" but the list order below is C → Rust → Go (not C → Go → Rust). Either the prose or the list order should be corrected so "respectively" is accurate.

Suggested change

	C, Go and Rust API are exposed respectively in
	- https://github.com/mratsim/constantine/tree/master/include
	- https://github.com/mratsim/constantine/tree/master/constantine-rust
	- https://github.com/mratsim/constantine/tree/master/constantine-go
	C, Go and Rust API are exposed respectively in
	- https://github.com/mratsim/constantine/tree/master/include
	- https://github.com/mratsim/constantine/tree/master/constantine-go
	- https://github.com/mratsim/constantine/tree/master/constantine-rust

[greptile-apps]

Unresolved TODO in audit-facing document

There is an open _TODO: tag a new version for audit_ note in the Library organization section. Since this document is intended to be shared with auditors and interested parties (Ethereum Foundation, client teams), it should have this resolved or at minimum tracked before the document is considered final.

[greptile-apps]

Missing newline at end of file

The file is missing a trailing newline, which is flagged by the diff (\ No newline at end of file). Adding a trailing newline is a standard convention.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}