Skip to content

INFRASTRUCTURE.md

Latest commit

 

History

History
60 lines (50 loc) · 4.36 KB

INFRASTRUCTURE.md

File metadata and controls

60 lines (50 loc) · 4.36 KB
Raw

NeuralYul Infrastructure — what's built, what's excluded

This document maps every component of the architecture specs to the code that implements it. The AI models and the training data are intentionally excluded; everything that surrounds them is here and runnable.

Excluded by design (the "AI model + data")

  • The 3-layer GIN backbone body, dual readout, NT-Xent / EMA / learnable-τ training loop.
  • The PPO policy/value networks, GAE, and the CMDP Lagrangian dual-ascent loop.
  • The Process Reward Model.
  • The YulCode dataset (350k contracts) and any checkpoints / .onnx weights.

These have typed seams in src/neuralyul/models/ so the infra is fully wired.

Spec → file map

Architecture component Spec ref Implementation
Hyperparameters / 36-d feature layout upd. 4.2, 6, 8.1 src/neuralyul/config.py
PDG parser (AST+CFG+DFG, labelled edges) upd. 4 src/neuralyul/pdg/parser.py
32-class vocab + 36-d featurizer upd. 4.2 src/neuralyul/pdg/node_features.py
Edge taxonomy (labels 0/1/2) upd. 4.1 src/neuralyul/pdg/edge_types.py
Augmentations NFM / EP / SE upd. 5 src/neuralyul/data/augmentations.py
PyG InMemoryDataset, two-view get upd. 7 src/neuralyul/data/dataset.py
Model boundary (encoder/policy/value/PRM) upd. 6, base 2.2 src/neuralyul/models/
24 Yul passes + solc abbreviations base 2.2 src/neuralyul/env/passes.py
solc driver (apply step sequence) base 3.3 src/neuralyul/env/solc_driver.py
Gymnasium env (reward = gas saved) base 3.1, 8.2.1 src/neuralyul/env/yul_env.py
Zero-copy gas bridge (mock + PyO3) base 3.2, 8.4 src/neuralyul/reward/gas_bridge.py
Shared-memory ring buffer (Python side) base 8.4 src/neuralyul/reward/ringbuffer.py
Differential fuzzer (output/state/gas) base 2.3 src/neuralyul/correctness/fuzzer.py
Z3 equivalence + KECCAK-as-UIF base 8.5 src/neuralyul/correctness/verifier.py
Ring buffer byte layout (Rust side) base 8.4 executor/src/protocol.rs
SPSC ring buffer (Rust worker side) base 8.4 executor/src/ringbuffer.rs
GasBackend trait + Mock + revm base 3.2, 8.4 executor/src/evm.rs
PyO3 GasEvaluator extension base 3.1 executor/src/lib.rs
Worker process (ring consumer) base 8.4 executor/src/main.rs
C++ feature extractor (Python parity) base 3.3 solc-plugin/src/FeatureExtractor.cpp
YulMLRunner ONNX wrapper base 3.3 solc-plugin/src/YulMLRunner.cpp
Suite.cpp integration hook base 3.3 solc-plugin/patches/suite_hook.md
Foundry wrapper (--ml-optimize/--super…) base 10 orchestration/foundry-plugin/
Superoptimizer daemon / API base 10 src/neuralyul/daemon.py

The runnable-today property

Because the gas evaluator has a dependency-free MockBackend, the entire control flow — parse → featurise → choose passes → compile via solc → measure gas → differential-fuzz → (Z3 verify) — runs end-to-end with only networkx + solc installed. Swapping in the real EVM is one Cargo feature (--features revm); swapping in a trained encoder/policy is one subclass in neuralyul.models. Nothing else moves.

Build matrix

Layer Always works Upgrade path
Gas measurement Python MockGasEvaluator maturin develop -m executor/Cargo.toml [--features revm]
Encoder input structural summary obs subclass models.GraphEncoder, load checkpoint
Pass selection env + manual/random seq subclass models.PassPolicy
Equivalence differential fuzzing pip install 'neuralyul[verify]' for Z3