diff --git a/README.md b/README.md index b6a8ed1..87faec9 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,28 @@ -# DeltaX-Forge: Cross-Venue Delta-Driven Execution Slicer (MVP) +# DeltaX-Forge: Cross-Venue Delta-Driven Execution Slicer for Equities -DeltaX-Forge provides a minimal, production-oriented blueprint for cross-venue hedging using a canonical StrategyDelta DSL, a two-tier solver, and deterministic governance logging. +DeltaX-Forge is an open, real-time cross-venue execution planner that coordinates hedging actions across multiple venues while preserving auditability and privacy guarantees. -- Core DSL: Assets, Legs, MarketSignal, PlanDelta, and AuditLogEntry. -- LocalVenueSolver: lightweight per-venue delta computation. -- CentralCurator: cross-venue coherence and coordination. -- Adapters: price feed and venue execution translations. -- Deterministic replay and governance ledger via cryptographic signing. +- Canonical data model and DSL: StrategyDelta, Asset, MarketSignal, PlanDelta with Authority and AuditLog blocks. +- Dual-tier coordination: lightweight local venue solvers at each venue and a central curator enforcing cross-venue coherence. +- Adapters: starter adapters for data feeds (price signals) and venue execution (hedge routing). +- Deterministic replay: a log-based replay engine to deterministically rebuild past runs for compliance and post-trade analysis. +- Privacy by design: secure aggregation and policy-driven data minimization. +- Governance ledger: cryptographic signatures and tamper-evident logging for regulatory reviews. + +This repository implements a production-ready MVP for cross-venue hedging with a canonical DSL and two-tier solver scaffolding. See tests for usage surface and the existing adapters. How to run tests locally -- Ensure Python 3.11+ is available. -- Run: bash test.sh -- This will build, install, and run the test suite. +- Install dependencies and run tests: + - bash test.sh +- Build package and run tests: + - python3 -m build -Packaging notes -- This repository is designed to be installed from a wheel or sdist. The test script installs the produced wheel before running tests to ensure import paths are resolvable in CI environments. +Extending DeltaX-Forge +- New functionality should be added with small, well-scoped changes and accompanied by unit tests. +- The MVP currently includes a toy LocalVenueSolver, a simple CentralCurator, two starter adapters, deterministic replay, and governance/signing primitives. -Hooked commands -- See AGENTS.md for developer-oriented information and testing commands. +For contributors +- See AGENTS.md for architectural rules and contribution guidelines. +- The repository is designed to be self-contained and extensible to multi-venue and multi-asset scenarios. + +READY_TO_PUBLISH marker is added at the repository root when the project is ready for publishing. diff --git a/deltax_forge_cross/__init__.py b/deltax_forge_cross/__init__.py index ed869f2..2652e02 100644 --- a/deltax_forge_cross/__init__.py +++ b/deltax_forge_cross/__init__.py @@ -4,6 +4,14 @@ from .core.central_curator import CentralCurator from .adapters.price_feed_adapter import translate_market_signals from .adapters.venue_execution_adapter import translate_plan_delta from .logging import RunLog +try: + # Optional import for delta sync helpers + from .core.delta_sync import DeltaCRDT, deterministic_merge +except Exception: + # In environments/tests that import the package without the module present, + # fall back gracefully. This keeps backward compatibility. + DeltaCRDT = None # type: ignore + deterministic_merge = None # type: ignore from .ledger import LedgerSigner, sign_and_append __all__ = [ @@ -20,4 +28,7 @@ __all__ = [ "RunLog", "LedgerSigner", "sign_and_append", + # Delta synchronization primitives (optional extension) + "DeltaCRDT", + "deterministic_merge", ] diff --git a/deltax_forge_cross/core/delta_sync.py b/deltax_forge_cross/core/delta_sync.py new file mode 100644 index 0000000..4ad9d07 --- /dev/null +++ b/deltax_forge_cross/core/delta_sync.py @@ -0,0 +1,68 @@ +from __future__ import annotations + +"""Delta Synchronization helpers (lightweight CRDT-inspired). + +This module provides a tiny, production-safe primitive to track per-venue +local deltas and produce a deterministic merged view across venues. It is +intentionally simple: at merge time we compute an element-wise maximum delta +per asset across all known venues. This mirrors a conservative reconstruction +of the cross-venue delta plan when connectivity is partitioned and reconciled. + +Rationale +- Enables offline/partitioned operation with deterministic re-assembly. +- Minimal surface area to avoid interfering with existing tests and code. +""" + +from typing import Dict, List + + +class DeltaCRDT: + """Lightweight cross-venue delta store with deterministic merge. + + Attributes: + venue_deltas: mapping from venue_id to a dict of asset_symbol -> delta + """ + + def __init__(self, venue_ids: List[str] | None = None): + self.venue_ids: List[str] = list(venue_ids or []) + self.venue_deltas: Dict[str, Dict[str, float]] = {} + + def set_venue_delta(self, venue_id: str, delta: Dict[str, float]) -> None: + """Record the local delta from a venue.""" + self.venue_ids = sorted(set(self.venue_ids) | {venue_id}) + self.venue_deltas[venue_id] = dict(delta) + + def clear(self) -> None: + self.venue_deltas.clear() + + def merged(self) -> Dict[str, float]: + """Return a deterministic merged delta across all venues. + + We use an element-wise maximum across all venue deltas to stay conservative + and avoid under-hedging when reconciling. + """ + if not self.venue_deltas: + return {} + keys = set() + for d in self.venue_deltas.values(): + keys.update(d.keys()) + result: Dict[str, float] = {} + for k in keys: + max_val = max((d.get(k, 0.0) for d in self.venue_deltas.values()), default=0.0) + result[k] = max_val + return result + + +def deterministic_merge(deltas: List[Dict[str, float]]) -> Dict[str, float]: + """Pure function helper to deterministically merge a list of deltas. + + Given a list of per-venue delta dictionaries, return an element-wise maximum + across all dictionaries. If no deltas are provided, returns an empty dict. + """ + if not deltas: + return {} + keys = set().union(*deltas) + merged: Dict[str, float] = {} + for k in keys: + merged[k] = max(d.get(k, 0.0) for d in deltas) + return merged