diff --git a/docs/exec-plans/active/C09.md b/docs/exec-plans/active/C09.md deleted file mode 100644 index a4750f3..0000000 --- a/docs/exec-plans/active/C09.md +++ /dev/null @@ -1,562 +0,0 @@ -# C09 — PREVRANDAO Value-Dependency Replacement Plan - -Status: Decision selected; implementation pending - -Planning risk: R1 - -Proposed implementation risk: R3 - -Owner: ArcReady maintainers - -Base branch: `main` - -Base SHA: `c17c8b4cf2288df825ef5d677b5fc9eba5674b74` - -Planning branch: `docs/c09-prevrandao-replacement-plan` - -Decision record: `docs/research/C09-D.md` - -Implementation plan: `docs/exec-plans/active/C09A.md` - -Completed research evidence: - -- C09-R1: parser and ownership audit -- C09-R2: 52-case source and project corpus -- C09-R3-A: bounded Solidity value-flow prototype -- C09-R3-B: bounded Foundry deployment-association prototype - -Selected disposition: Build one private analyzer with two temporary public -compatibility shells. Production remains blocked until C09-D and C09A are merged -and independently reviewed. - -C09A is the next implementation milestone. The compatibility inventory target -remains `19 known / 16 default / 7 wallet / 4 canonical`. - -Last reviewed: 2026-08-06 - -## 1. Product problem - -ArcReady currently exposes two default critical rules for one underlying Arc -compatibility problem: - -```text -wallet/PREVRANDAO_NOT_SUPPORTED -bridge/NO_PREVRANDAO_RELAY_SELECTION -``` - -Both rules use file-level Arc keywords and line-level PREVRANDAO keywords. The -wallet rule reports any active occurrence. The bridge rule adds relay or -randomness words on the same line. - -Neither detector proves that the opcode value affects application behavior. -Both detectors also treat `mixHash` as equivalent source text without sufficient -official support. - -C09 replaces these duplicate keyword heuristics with an evidence-backed model of -Arc-owned PREVRANDAO value dependency. It must not preserve blanket symbol -matching merely to retain finding count. - -## 2. Pinned first-party premise - -Current Arc documentation states: - -- Arc targets the Prague EVM hard fork; -- `PREVRANDAO` always returns `0` on Arc; -- the value does not provide randomness on Arc; -- bridge contracts must not use `block.prevrandao` for relay shuffling or random - selection; -- bridge integrations should replace such dependency with an external oracle or - deterministic round-robin design. - -Pinned Arc sources: - -- `https://docs.arc.io/integrate/infrastructure` -- `https://docs.arc.io/integrate/infrastructure/bridges` - -Current Solidity documentation states: - -- `block.prevrandao` is the post-Paris beacon-chain random value; -- inline assembly `prevrandao()` is introduced for Paris and later targets; -- `block.difficulty` becomes a deprecated alias for `block.prevrandao` for - post-Paris EVM targets; -- inline assembly `difficulty()` is disallowed for post-Paris targets. - -Pinned Solidity sources: - -- `https://docs.soliditylang.org/en/latest/cheatsheet.html` -- `https://docs.soliditylang.org/en/latest/using-the-compiler.html` -- `https://docs.soliditylang.org/en/latest/yul.html` - -These sources do not establish blanket source-text equivalence between -`mixHash` and PREVRANDAO. - -## 3. Current implementation audit - -### Wallet rule - -`packages/arcready/rules/wallet/prevrandao-not-supported.ts` currently: - -- scans every file discovered for the wallet preset; -- gates on broad Arc words or Arc Testnet chain ID; -- matches `block.prevrandao`, `PREVRANDAO`, `prevrandao`, or `mixHash` on any - active line; -- skips obvious comments, documentation lines, and negative guidance; -- emits one file-level critical finding. - -The current wallet test proves only one same-file Arc chain ID and one direct -`block.prevrandao` assignment. It does not prove a randomness or behavior sink. - -### Bridge rule - -`packages/arcready/rules/bridge/no-prevrandao-relay-selection.ts` currently: - -- scans every file discovered for the bridge preset; -- gates on broad Arc and bridge words; -- matches the same PREVRANDAO and `mixHash` keyword set; -- additionally requires a relay, selection, shuffle, or randomness word on the - same line; -- emits one file-level critical finding. - -The current bridge test uses a direct modulo expression, but the detector itself -does not parse that value dependency. - -### Catalog state - -Both catalog entries already acknowledge: - -- low default confidence; -- symbol presence does not prove application behavior; -- same-line relay/randomness words do not establish selection dependency; -- blanket `mixHash` equivalence is not sufficiently documented. - -C09 must resolve those admitted limitations rather than only rename or merge the -existing regexes. - -## 4. Decision: Research / Replace - -C09 must not harden either current keyword detector. - -The existing public rules are replacement candidates. Research must end in one -reviewed implementation disposition: - -1. **Build shared analyzer with compatibility shells.** Implement one private - bounded Solidity analyzer and use thin legacy rule integrations only where - preset compatibility requires them. -2. **Build one consolidated public rule.** Introduce one public rule only when - its preset, finding category, public ID, compatibility migration, and inventory - behavior are all explicitly reviewed. -3. **Advice-only migration.** Default-exclude or downgrade the old rules when - reliable value dependency cannot be proven within product limits. -4. **Retire.** Remove unsupported heuristics when neither a bounded analyzer nor - useful optional guidance is justified. - -`Replace` is the migration action, not the final implementation disposition. - -A successful C09 outcome cannot leave both current critical keyword heuristics -unchanged. - -## 5. Public-ID and preset constraint - -ArcReady currently has only three runtime presets and rule categories: - -```text -wallet -bridge -app-kit -``` - -The `solidity` value currently exists only as an internal rule-pack label. It is -not a runtime preset or a public finding category. - -C09 must not add a new `solidity` preset merely to obtain a cleaner rule name. -Doing so would widen config schemas, CLI behavior, project detection, reporters, -fixtures, documentation, and compatibility contracts. - -The research decision must compare these bounded options: - -### Option A — shared private analyzer, two temporary public shells - -- one parser and evidence model; -- legacy wallet and bridge rule IDs remain temporarily; -- each shell emits only analyzer records applicable to its preset contract; -- duplicate execution and duplicate findings are prevented; -- one later migration may retire or consolidate the shells. - -### Option B — one existing ID survives - -- choose either wallet or bridge ID as the public rule; -- document why that preset truthfully represents all supported sinks; -- define behavior when only the other preset is selected; -- deprecate or retire the other ID without silently losing coverage. - -### Option C — one new public ID - -- introduce a new ID only after explicitly reviewing its existing-preset - placement; -- do not add a new runtime preset or category in C09; -- provide a bounded compatibility period for both old IDs; -- keep deterministic order and inventory counts explicit. - -C09-D must select exactly one option before production integration begins. - -## 6. Candidate bounded source surface - -The private feasibility prototype may inspect plain Solidity `.sol` files only. -It must fail closed for unsupported syntax. - -Initial exact source candidates: - -- direct `block.prevrandao` expression; -- direct inline assembly `prevrandao()` result; -- optional `block.difficulty` only when the same repository proves a post-Paris - or later EVM target through an exact supported compiler configuration; -- direct or one single-assignment same-function local binding; -- no arbitrary bare `PREVRANDAO` identifiers; -- no blanket `mixHash` matching; -- no JavaScript, TypeScript, JSON, YAML, Markdown, or prose matching. - -Supporting `block.difficulty` without proven compiler/EVM-target context is not -approved. Supporting inline assembly does not authorize general Yul analysis. - -### Parser and dependency feasibility - -The package currently depends on TypeScript and does not include a Solidity -parser. C09 must not assume that the TypeScript compiler can parse Solidity or -prove contract/function ownership. - -C09-R1 must compare bounded parser inputs: - -- a maintained Solidity parser dependency; -- compiler-produced standard JSON AST supplied as research input; -- a deliberately narrow custom tokenizer/parser for only the approved grammar. - -The comparison must record: - -- supported Solidity and Yul versions; -- malformed-source and recovery behavior; -- source offsets and deterministic AST ownership; -- licensing, maintenance, package size, and supply-chain risk; -- test-only versus production dependency cost; -- whether generated or compiler AST input would change the user workflow; -- fail-closed behavior for unsupported syntax. - -A research prototype may use a temporary test-only parser dependency or retained -AST fixture. No production dependency or compiler requirement is authorized -before C09-D selects an implementation architecture. - -## 7. Candidate reportable dependencies - -A source occurrence is not reportable merely because it reads PREVRANDAO. - -A candidate critical or warning finding must prove that a supported value reaches -one direct behavior sink inside the same function and same contract candidate. - -Initial sink families for feasibility testing: - -- modulo or index selection from a non-empty collection; -- relay, validator, sequencer, committee, winner, or recipient selection; -- direct shuffle or ordering key; -- direct lottery, raffle, allocation, assignment, or sampling decision; -- direct authorization or eligibility branch; -- direct storage of a value explicitly named and consumed as a randomness seed - within the same bounded function. - -The prototype must distinguish: - -- reading or logging the value; -- returning the value from a diagnostic function; -- comparing the value to zero as a compatibility check; -- hashing the value without a supported behavioral sink; -- storing an unused value; -- using the value in a reportable decision. - -Only the last class is a candidate compatibility finding. - -## 8. Arc ownership contract - -C09 must not borrow Arc ownership from unrelated repository text. - -Research must test bounded ownership sources such as: - -- exact Arc Testnet chain ID in a supported deployment configuration; -- exact official Arc RPC or imported `arcTestnet` evidence in a same-project - deployment surface; -- an exact supported Foundry or Hardhat network configuration associated with - the contract deployment path; -- explicit Arc-only contract or deployment naming only when paired with stronger - configuration evidence. - -Unsupported ownership includes: - -- an arbitrary `Arc` comment or string; -- README or documentation prose; -- an unrelated wallet or bridge file elsewhere in the repository; -- a multichain configuration without contract-to-network association; -- imported or computed network values that cannot be resolved safely; -- a Solidity contract with no deployment ownership evidence. - -A `.sol`-only parser cannot prove that the contract is deployed to Arc merely -because another repository file mentions Arc. - -C09-R3 must therefore separate ownership feasibility: - -### C09-R3-A — source and value-dependency feasibility - -- evaluate Solidity source ownership, function ownership, bounded local flow, and - supported sinks using explicit synthetic ownership input in the research - harness; -- do not treat that harness input as proof that production repository ownership - exists; -- determine whether the parser can classify source/value behavior independently - of deployment association. - -### C09-R3-B — deployment-association feasibility - -- separately test one bounded association between a Solidity contract and an - exact Arc deployment configuration; -- define the accepted file types, directory relationship, contract/deployment - identifier ownership, ambiguity rules, and deterministic ordering; -- fail closed for imported, computed, multichain, duplicate, or conflicting - deployment configuration; -- treat meaningful production emission as blocked when no reviewed association - can prove that the analyzed contract targets Arc. - -The first production implementation must not silently convert synthetic R3-A -ownership into repository evidence. Wider project association requires a -separate reviewed capability. - -## 9. Required source corpus - -C09-R2 must materialize complete-source fixtures with unique IDs and expected -classification. The corpus must separate source evidence, Arc ownership, -value-flow evidence, sink ownership, and public-emission eligibility. - -### Positive candidate dimensions - -- direct `block.prevrandao % relayers.length`; -- direct cast then modulo; -- one single-assignment local seed binding then direct modulo; -- direct relay or winner array indexing; -- exact direct authorization branch derived from PREVRANDAO; -- exact inline assembly `prevrandao()` with a supported direct sink; -- both LF and CRLF; -- one supported Arc ownership shape. - -### Safe or non-reportable dimensions - -- value read but unused; -- logging, event emission, debug return, or diagnostics; -- explicit zero-compatibility assertion; -- comment, documentation, string, test description, and identifier name; -- negative guidance; -- hashing without a supported sink; -- dead assignment; -- Ethereum-only or unknown deployment ownership; -- a correct deterministic replacement; -- a file that mentions Arc but deploys elsewhere. - -### Unsupported dimensions - -- aliases deeper than the approved bound; -- mutation, reassignment, branch joins, loops, recursion, callbacks, or modifiers; -- imported values or inherited helper functions; -- cross-contract and cross-file flow; -- computed array, collection, or sink ownership; -- assembly blocks beyond exact direct `prevrandao()` extraction; -- unknown compiler or EVM target for `block.difficulty`; -- inline assembly `difficulty()`; -- arbitrary `mixHash` identifiers; -- malformed Solidity; -- generated sources and vendored dependencies unless explicitly in scan scope. - -### Adversarial dimensions - -- unrelated PREVRANDAO read and relay words on the same line; -- relay selection and PREVRANDAO in different functions; -- multiple contracts in one file; -- supported source occurrence owned by one contract and sink owned by another; -- comments between tokens; -- shadowed local variables; -- duplicate declarations; -- source strings containing Solidity snippets; -- a value overwritten before the sink; -- a sink that uses another seed; -- collection length zero or unknown when the expression depends on modulo; -- multiple candidates with deterministic earliest selection. - -## 10. Research phases - -### C09-R1 — premise, inventory, and architecture audit - -- pin current Arc and Solidity semantics; -- inventory both public IDs, exports, presets, catalog metadata, tests, fixtures, - reporters, and default finding-count impact; -- document public preset/category constraints; -- inventory Solidity parser, compiler-AST, and narrow-tokenizer options; -- record parser version coverage, malformed-source behavior, licensing, - maintenance, supply-chain, and production-dependency cost; -- remove blanket `mixHash` equivalence from the proposed premise; -- define the minimum Arc ownership and value-dependency evidence. - -### C09-R2 — complete-source corpus - -- materialize the required positive, safe, unsupported, and adversarial cases; -- record separate internal classifications for source, ownership, dependency, - sink, and public-emission eligibility; -- include exact old-rule false positives and false negatives; -- add machine validation for fixture IDs and expected fields. - -### C09-R3 — private disposable feasibility prototype - -#### R3-A — parser, source, and dependency experiment - -- use only the reviewed research parser input selected by R1; -- parse Solidity without changing public rule behavior; -- use explicit synthetic Arc ownership input only to isolate parser and - value-dependency feasibility; -- prove exact contract/function source ownership, bounded local flow, and - supported direct sinks; -- evaluate direct `block.prevrandao` first; -- evaluate inline assembly and `block.difficulty` only as separate bounded - families; -- run the complete corpus and source-level pressure shapes. - -#### R3-B — bounded Arc deployment association - -- test one explicit association between the analyzed contract and an exact Arc - deployment configuration; -- keep file types, directory relation, identifiers, ambiguity, and conflict - handling bounded and deterministic; -- run deployment-association false-positive and false-negative pressure cases; -- report production public-emission eligibility as blocked when the association - cannot be proven. - -Discard the prototype if either experiment requires a general Solidity data-flow -platform, unrestricted cross-file analysis, or an unreviewed production parser -dependency. - -### C09-D — implementation and migration decision - -Independent review must select: - -- shared analyzer with compatibility shells; -- one surviving existing ID; -- one new ID under an existing preset; -- Advice-only migration; or -- Retire. - -The decision must also pin: - -- final rule ID or temporary IDs; -- preset registration and finding category; -- default severity and confidence; -- old-ID deprecation or removal behavior; -- inventory and fixture-count changes; -- duplicate prevention and deterministic order; -- canonical FindingV2 eligibility or explicit non-eligibility. - -No production implementation begins before C09-D is approved. - -## 11. Build phases if authorized - -Only a C09-D Build disposition may authorize these phases. - -### C09-E1 — parser and source ownership - -- implement the approved private parser boundary; -- recognize only approved source forms; -- reject `mixHash` and unsupported `block.difficulty` cases; -- prove supported Arc deployment ownership; -- emit private records only. - -### C09-E2 — bounded dependency and sink proof - -- prove direct or approved one-binding local value flow; -- prove exact supported behavior sinks; -- fail closed for mutation, aliases, joins, cross-function flow, and unsupported - assembly; -- maintain deterministic offsets and classifications. - -### C09-E3 — public integration and legacy migration - -- integrate only the C09-D-approved public-ID strategy; -- prevent duplicate execution and findings across wallet and bridge presets; -- update catalog, docs, tests, inventory, fixtures, scoring, reporters, and CLI - expectations intentionally; -- retain or deprecate old IDs only as explicitly approved; -- do not introduce a new runtime preset or generic plugin registry. - -### C09-E4 — closeout - -- independently review every semantic phase; -- run full repository verification; -- record final IDs, counts, supported grammar, unsupported cases, and expansion - triggers; -- move this plan to completed only after merge evidence is recorded. - -## 12. Non-goals - -C09 does not include: - -- a general Solidity AST, CFG, SSA, taint, symbolic-execution, or data-flow - platform; -- vulnerability analysis or randomness-quality auditing outside the Arc - compatibility premise; -- runtime deployment verification or RPC calls; -- oracle selection or implementation; -- cross-file inheritance or library resolution; -- arbitrary Yul analysis; -- blanket `mixHash` equivalence; -- automatic support for all compiler versions or EVM targets; -- a new `solidity` runtime preset or public category; -- changes to canonical FindingV2 before a separate eligibility review; -- C10 App Kit implementation. - -## 13. Risk controls - -- keep research artifacts private or under `docs/research` and test-only scope; -- do not add a production Solidity parser dependency before C09-D; -- do not change either production rule during R1 through R3; -- use complete-source fixtures rather than keyword obligations; -- keep source recognition, Arc ownership, value dependency, sink proof, and - public emission as separate internal decisions; -- prefer bounded false negatives over critical false positives; -- preserve current public IDs until C09-D selects a migration; -- no force push or history rewriting; -- every semantic phase requires independent blocker, major, and minor counts; -- stop and redesign if one shared rule requires a new runtime preset or a general - analyzer framework. - -## 14. Planning validation - -This planning PR changes executable behavior: none. - -Required checks: - -```powershell -corepack pnpm exec prettier --check docs/exec-plans/active/C09.md -git diff --check -``` - -The plan requires independent review before merge. - -## 15. Exit criteria - -C09 planning is complete only when: - -- official Arc and Solidity semantics are pinned without contradiction; -- the unsupported blanket `mixHash` premise is explicitly removed; -- current false-positive and false-negative classes are documented; -- the Arc ownership boundary separates synthetic source experiments from - production deployment association; -- parser and dependency feasibility is explicitly gated; -- reportable value-dependency and sink families are explicit; -- public-ID and preset constraints are documented; -- the corpus and prototype phases are bounded; -- no production implementation is authorized by the plan itself; -- independent review reports `APPROVE` with zero blocker, major, and minor - findings. - -C09 implementation is complete only after a later C09-D disposition and all -authorized build or migration phases are merged, reviewed, verified, and closed -out. diff --git a/docs/exec-plans/active/C09A.md b/docs/exec-plans/active/C09A.md deleted file mode 100644 index 1f66edf..0000000 --- a/docs/exec-plans/active/C09A.md +++ /dev/null @@ -1,470 +0,0 @@ -# C09A — Bounded PREVRANDAO Analyzer Implementation Plan - -Status: Planned - -Planning risk: R2 - -Implementation risk: R3 - -Owner: ArcReady maintainers - -Base branch: `main` - -Base SHA: `16e3d00a26784655d5049fbffab6618e34e98297` - -Planning branch: `docs/c09-d-bounded-build-decision` - -Decision record: `docs/research/C09-D.md` - -Last reviewed: 2026-08-06 - -## 1. Goal - -Replace the two existing PREVRANDAO keyword heuristics with one production -private analyzer that emits only when both of these evidence layers are proven: - -1. bounded Solidity source, same-function value dependency, and supported sink; -2. exact Foundry contract-to-Arc deployment association. - -Retain the two existing public rule IDs as temporary compatibility shells without -adding a new runtime preset, finding category, or public ID. - -## 2. Current state - -Current public rules: - -```text -wallet/PREVRANDAO_NOT_SUPPORTED -bridge/NO_PREVRANDAO_RELAY_SELECTION -``` - -Both are default critical and both currently rely on broad Arc text plus -line-level PREVRANDAO or `mixHash` matching. The bridge rule adds same-line relay -or randomness words. - -C09 research established: - -- blanket `mixHash` equivalence is unsupported; -- symbol presence does not prove behavior; -- R3-A source/value analysis is feasible within a bounded grammar; -- R3-B exact Foundry Arc ownership is feasible for one artifact family; -- no production parser dependency or behavior has yet been introduced. - -## 3. Target architecture - -### Shared analyzer - -Create one private analyzer with a scan-scoped cache. It owns: - -- lazy parser loading; -- supported `.sol` discovery; -- AST parse and diagnostics; -- source and function ownership; -- bounded binding and sink classification; -- concrete contract identity; -- Foundry broadcast discovery and parsing; -- exact contract-to-chain association; -- private record composition and deterministic ordering. - -The analyzer returns private records only. It must not import public finding or -reporter types. - -### Compatibility shells - -The existing wallet and bridge rule modules become thin adapters. - -They may: - -- request the shared private records; -- filter records by the reviewed shell ownership class; -- convert each owned record into the existing public Finding shape; -- apply existing config severity overrides through normal runtime execution. - -They must not: - -- parse source independently; -- re-run Foundry association independently; -- contain PREVRANDAO or `mixHash` keyword detection; -- emit the same private record twice; -- borrow Arc ownership from broad text. - -## 4. Private record contract - -Each reportable private record must include enough evidence for deterministic -conversion and review: - -```text -sourceFile -contractName -functionName -sourceKind -sourceOffset -bindingKind -sinkKind -sinkOffset -shellOwner -foundryArtifactPath -chainId -contractAddress -confidence -``` - -The record must not claim runtime behavior, transaction success, deployed bytecode -identity, or live-chain verification. - -### Shell ownership - -Allowed values: - -```text -bridge-relay -wallet-compatibility -``` - -`bridge-relay` requires a supported sink whose exact function, collection, or -selected-entity identifiers establish relay, relayer, validator, sequencer, or -committee behavior. - -`wallet-compatibility` owns the remaining supported selection, authorization, -eligibility, winner, recipient, allocation, and ordering records during the -compatibility period. - -Ambiguous shell ownership fails closed and emits no public finding. - -A record emits only through its exact owner shell when that shell rule is -selected. The other shell never borrows it. E2 must pin wallet-only, bridge-only, -both-presets, neither-owner, and ambiguous-owner behavior. When both shells are -selected, one eligible private record still becomes exactly one public finding. - -## 5. Dependency and packaging contract - -C09A-E1 may add exactly: - -```text -@solidity-parser/parser@0.20.2 -``` - -as a production dependency only after the dependency review passes. - -Required dependency checks: - -- exact version and integrity are recorded in `pnpm-lock.yaml`; -- package license is MIT-compatible; -- installed and packed contents are measured; -- zero runtime transitive dependencies are confirmed; -- Node 22 import succeeds; -- tsup ESM build and declaration generation succeed; -- packed ArcReady package can lazy-load the parser; -- non-Solidity scans do not import the parser; -- no `solc`, `solc-js`, Tree-sitter, Foundry binary, or additional parser is - introduced. - -The parser should remain external to the main tsup bundle only when the packed -package includes and resolves it correctly. Bundling or externalization must be -decided from package smoke evidence, not assumption. - -## 6. Supported source grammar - -The first production version supports only R3-reviewed complete `.sol` source -families. - -### Source forms - -- exact `block.prevrandao`; -- one approved direct cast around the source; -- one same-function single-assignment local binding; -- exact inline assembly `prevrandao()` assignment; -- `block.difficulty` only after a separately reviewed exact post-Paris EVM-target - evidence adapter exists. - -`block.difficulty` should remain disabled in E1–E4 unless that adapter is -implemented and independently reviewed within the same bounded milestone. - -### Supported sinks - -- direct modulo/index collection selection; -- approved direct relay, validator, sequencer, committee, winner, recipient, - allocation, authorization, eligibility, and ordering expressions; -- same function and same contract only; -- deterministic earliest reportable candidate when multiple source occurrences - exist. - -### Safe observations - -The analyzer must not report: - -- unused reads; -- diagnostic returns; -- logs or event-only observations; -- explicit zero compatibility assertions; -- hashing without a supported behavior sink; -- deterministic replacement logic. - -## 7. Foundry ownership contract - -Supported artifact family: - -```text -broadcast/