Skip to content

chore(audit): add design intent comments and TODO markers from security review#301

Open
Richard1048576 wants to merge 4 commits intoGalxe:mainfrom
Richard1048576:feat/add-design-intent-comments
Open

chore(audit): add design intent comments and TODO markers from security review#301
Richard1048576 wants to merge 4 commits intoGalxe:mainfrom
Richard1048576:feat/add-design-intent-comments

Conversation

@Richard1048576
Copy link
Collaborator

Description

This PR addresses the findings from the recent external security audit (GRETH-008 through GRETH-075) by annotating the gravity-reth codebase. This does not involve functional feature changes; instead, it provides formal documentation on our implementation mechanisms to prevent redundant auditing efforts and scopes the remaining work.

The annotations are separated into two distinct categories:

1. Design Intent Declarations

These comments clarify complex or counter-intuitive code segments that reflect explicit, structural decisions made by the core team. These are "By-Design" and answer potential auditor questions:

  • Consensus & Finality (GRETH-009, 040): Clarified our strict immediate finality BFT model, and the intentional use of zero-signature transaction structures for System Caller.
  • Storage Sharding & Cache Overlay (GRETH-034, 035, 046, 069): Documented the atomicity and consistency guarantees of the Gravity Cache overlay to mitigate the lack of cross-database snapshots in our 3-DB RocksDB sharding setup.
  • Parallel Pipeline (GRETH-057, 072): Addressed the specific usage of Atomic orderings in parallel executions, and validator-only history indexing skips.
  • Oracle & Relayer (GRETH-058, 059, 062): Documented the threat model for relying on EVM RPCs without TLS pinning, justified JWK type parsing logic, and the relaxed atomic synchronization of the cursor.
  • System Hardening (GRETH-060, 064): Detailed deliberate panics in configuration fetchers (to prevent data corruption from state desynchronisation) and safe sub-ether voting power truncation.

2. Verified TODO Items

These markers acknowledge actual bugs, architectural debts, or vulnerabilities raised by the audit that require future remediation:

  • Liveness & Deadlocks: Addressed unbounded barriers/timeouts (GRETH-029) and the unimplemented BLOCKHASH opcode (GRETH-031).
  • Resource Constraints: Marked unbounded asynchronous channels and task explosion risks in the relayer (GRETH-036, 045).
  • Gas Model Validations: Flagged severe gas-underpricing risks discovered in BLS12-381 and Mint precompiles (GRETH-065, 066), plus missing supply caps (GRETH-049).
  • Relayer & Recovery Bugs: Marked the catastrophic fromBlock defaulting edge case (GRETH-063), nonce type-truncation overflow (GRETH-043), and pipeline checkpoint recovery corruption risks (GRETH-070).
  • Code Duplication & Legacy: Flagged duplicated canonical transaction handlers (GRETH-041) and non-operative proposer arrays (GRETH-042).

Affected Scope

  • 22 modules overall mainly spanning crates/pipe-exec-layer-ext-v2, crates/engine/tree, and crates/gravity-storage.

Richard1048576 and others added 4 commits February 24, 2026 12:34
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Annotate 22 source files with Design Intent and TODO comments covering
all GRETH audit findings (GRETH-008 through GRETH-075). Design Intent
comments explain intentional behavior to prevent re-auditing. TODO
markers flag genuine issues for future remediation.
@Richard1048576 Richard1048576 force-pushed the feat/add-design-intent-comments branch from 98f78f8 to 7fc6959 Compare March 18, 2026 12:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant