# DeltaTrace

Deterministic replay, latency accounting, and compliance tracing for live market-execution pipelines.

DeltaTrace provides a small, production-oriented Python package for capturing market events as a causal graph, replaying them deterministically, and writing a tamper-evident audit trail for governance review.

## What It Does

- Models market-data ticks, signals, plan deltas, orders, fills, and risk checks as graph nodes.
- Links nodes with causal edges and latency measurements.
- Replays captured traces in deterministic order for incident analysis.
- Signs audit entries with Ed25519 and chains them with SHA-256 hashes.
- Includes two starter adapters:
  - FIX feed adapter for FIX-like market data messages.
  - Sandbox exchange adapter for order/fill simulation.

## Package Layout

- `deltatrace.event_graph`: event and DAG primitives.
- `deltatrace.replay_engine`: deterministic replay runner.
- `deltatrace.audit_log`: signed audit log with hash chaining.
- `deltatrace.adapters`: FIX and sandbox adapters.
- `deltatrace.demo`: end-to-end example pipeline.

## Install

```bash
pip install -e .
```

## Run the Demo

```bash
python -m deltatrace.demo
```

## Test And Build

```bash
./test.sh
```

This script installs dependencies, verifies `python -m build`, runs the test suite, and executes the demo.

## Publishing Notes

- Project metadata lives in `pyproject.toml`.
- The package README is wired as the long description for distribution builds.
- The build backend is setuptools and supports standard wheel/sdist creation.

## License

MIT