dilanj123/wire-to-decision

How dilanj123/wire-to-decision works

Wire-to-Decision is an FPGA datapath that converts a framed post-MAC Ethernet stream into a bounded order-book mutation and, when configured thresholds are crossed, a BUY/SELL event. The documented Architecture A flow validates Ethernet/IP/UDP and Mold framing, decodes the supported ITCH subset, updates order state, then evaluates a decision. The Python package is a functional reference oracle; the C++ replay checker independently derives decisions for comparison with RTL-exported logs. Edges among RTL stages follow the README’s datapath; model orchestration is supported by the oracle excerpt. RTL internals and C++ call paths were not sampled.

Main entry points: oracle.py Reference oracle · checker.cpp Replay checker · framing.py Packet framing model · book.py Order book model

Components 30

Ingress and framing

Ingress buffer rtl/common/wire_ingress_buffer.sv
64-to-8 gearbox rtl/arch_a/wire_gearbox_64to8.sv
Ethernet parser rtl/arch_a/wire_eth_parser.sv
IPv4 parser rtl/arch_a/wire_ipv4_parser.sv
UDP parser rtl/arch_a/wire_udp_parser.sv
Mold header sequence rtl/arch_a/wire_mold_header_seq.sv
Mold message framer rtl/arch_a/wire_mold_message_framer.sv
Optional CDC FIFO rtl/common/wire_async_fifo.sv

Mutation and decision

ITCH decoder rtl/arch_a/wire_itch_decoder.sv
Order store rtl/common/wire_order_book.sv
Decision engine rtl/common/wire_decision_engine.sv
Architecture A top rtl/arch_a/wire_arch_a_functional_top.sv

Python reference model

Packet framing model model/python/wire_to_decision/framing.py
Mold parser model model/python/wire_to_decision/mold.py
ITCH decoder model model/python/wire_to_decision/itch.py
Order book model model/python/wire_to_decision/book.py
Order-set hash model/python/wire_to_decision/hash.py
Decision model model/python/wire_to_decision/decision.py
IPv4 checksum model/python/wire_to_decision/checksum.py
Reference oracle model/python/wire_to_decision/oracle.py
Canonical types model/python/wire_to_decision/types.py
Model constants model/python/wire_to_decision/constants.py
Model validation model/python/wire_to_decision/errors.py

Replay checking

Checker CLI tools/cpp/main.cpp
Replay checker tools/cpp/checker.cpp
Checker interfaces tools/cpp/checker.hpp

Other components

Post-MAC stream
Decision event
RTL decision log
Comparison result

Connections 27

Post-MAC stream → Ingress buffer: accepts beats README.md
Ingress buffer → 64-to-8 gearbox: streams beats README.md
64-to-8 gearbox → Ethernet parser: serializes bytes README.md
Ethernet parser → IPv4 parser: passes payload README.md
IPv4 parser → UDP parser: passes datagram README.md
UDP parser → Mold header sequence: passes payload README.md
Mold header sequence → Mold message framer: frames messages README.md
Mold message framer → ITCH decoder: passes messages README.md
ITCH decoder → Order store: emits mutations README.md
Order store → Decision engine: provides totals README.md
Decision engine → Decision event: emits event README.md
Optional CDC FIFO → Architecture A top: streams across clocks README.md
Post-MAC stream → Optional CDC FIFO: optional beats README.md
Reference oracle → Packet framing model: calls framing model/python/wire_to_decision/oracle.py
Reference oracle → ITCH decoder model: decodes messages model/python/wire_to_decision/oracle.py
Reference oracle → Order book model: owns state model/python/wire_to_decision/oracle.py
Reference oracle → Decision model: owns decisions model/python/wire_to_decision/oracle.py
Packet framing model → Mold parser model: parses Mold model/python/wire_to_decision/framing.py
Packet framing model → IPv4 checksum: checks header model/python/wire_to_decision/framing.py
ITCH decoder model → Mold parser model: reads framed payload model/python/wire_to_decision/itch.py
Order book model → Order-set hash: indexes orders model/python/wire_to_decision/book.py
Decision model → Order book model: applies mutation model/python/wire_to_decision/decision.py
Checker CLI → Replay checker: runs checker
Replay checker → Checker interfaces: uses interfaces tools/cpp/checker.cpp
Checker CLI → Checker interfaces: uses interfaces tools/cpp/main.cpp
Replay checker → RTL decision log: compares decisions README.md
Replay checker → Comparison result: reports mismatches README.md

Drawn by GitDiagram on November 12, 2026 from the repository's file tree, README and source files. Read as Markdown ·