diff --git a/README.md b/README.md index 87faec9..4f53249 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,35 @@ -# DeltaX-Forge: Cross-Venue Delta-Driven Execution Slicer for Equities +# DeltaX-Forge: Cross-Venue Delta-Driven Execution Slicer (MVP) -DeltaX-Forge is an open, real-time cross-venue execution planner that coordinates hedging actions across multiple venues while preserving auditability and privacy guarantees. +This repository implements a minimal, production-oriented MVP of DeltaX-Forge: +- Canonical StrategyDelta DSL with Assets, Legs, MarketSignal, PlanDelta, and AuditLog +- Lightweight LocalVenueSolver per venue and a CentralCurator coordinating across venues +- Adapters to translate MarketSignal -> feed data and PlanDelta -> execution maps +- Deterministic replay via RunLog for post-trade analysis and audits +- Governance-friendly ledger (HMAC-based signatures) for deterministic integrity checks +- A skeleton EnergiBridge binding to bootstrap adapter interoperability -- 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. +Architecture highlights +- Canonical data model and DSL (StrategyDelta, Asset, MarketSignal, PlanDelta) +- Dual-tier coordination: Local venue solvers + central curator +- Adapters for data feeds and execution (price_feed_adapter, venue_execution_adapter) +- Deterministic replay and auditability (RunLog) +- Privacy-friendly design with per-message metadata and governance ledger (LedgerSigner) How to run tests locally -- Install dependencies and run tests: - - bash test.sh -- Build package and run tests: - - python3 -m build +- This project uses the standard packaging flow: + 1) Build distribution: python3 -m build + 2) Install the produced wheel: python3 -m pip install dist/*.whl + 3) Run tests: pytest -q -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. +Notes +- The EnergiBridge module under deltax_forge_cross/bridge/ provides a minimal + scaffold to bootstrap cross-venue adapter interoperability. It is intentionally + lightweight to avoid impacting the current MVP tests. +- This README intentionally documents the MVP boundaries and extension points for + future work aligned with the cross-venue, audited DeltaX-Forge roadmap. -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. +Contributing +- If you add new features, ensure unit tests cover them and keep changes scoped. +- Update README and AGENTS.md as architecture evolves. -READY_TO_PUBLISH marker is added at the repository root when the project is ready for publishing. +License: MIT diff --git a/deltax_forge_cross/bridge/energi_bridge.py b/deltax_forge_cross/bridge/energi_bridge.py new file mode 100644 index 0000000..f70cba7 --- /dev/null +++ b/deltax_forge_cross/bridge/energi_bridge.py @@ -0,0 +1,60 @@ +from __future__ import annotations + +"""EnergiBridge (Skeleton) + +Minimal, vendor-agnostic binding layer to map DeltaX primitives to a +canonical IR and expose simple translation entry points for adapters. + +This MVP skeleton provides the surface area for interop without changing +existing behavior or test expectations. It can be extended to support a full +EnergiBridge-style binding in later iterations. +""" + +from typing import Dict + +from deltax_forge_cross.dsl import StrategyDelta, MarketSignal, PlanDelta + + +def to_canonical_ir(strategy_delta: StrategyDelta) -> Dict: + """Translate a StrategyDelta into a minimal canonical IR dict. + + This is intentionally lightweight: it captures basic asset symbols, + budgets, and market signals when present. The result is designed to be + consumed by adapters and the central coordinator in a future extension. + """ + assets = [a.symbol for a in strategy_delta.assets] if strategy_delta.assets else [] + + signals = {} + if getattr(strategy_delta, "signals", None): + for s in strategy_delta.signals: + signals[s.symbol] = { + "price": s.price, + "liquidity": s.liquidity, + "latency_proxy": s.latency_proxy, + } + + # Minimal PlanDelta representation; actual delta actions would be populated by solvers + plan = { + "hedge_updates": strategy_delta.legs[0].asset.symbol if strategy_delta.legs else {}, + } + + return { + "LocalArbProblem": { + "assets": assets, + "target_delta_budget": getattr(strategy_delta, "delta_budget", 0.0), + "liquidity_budget": getattr(strategy_delta, "vega_budget", 0.0), + "latency_budget": getattr(strategy_delta, "gamma_budget", 0.0), + }, + "SharedSignals": signals, + "PlanDelta": plan, + } + + +def from_canonical_plan(plan_delta: PlanDelta) -> PlanDelta: + """Identity mapping placeholder for converting a canonical PlanDelta back. + + In a full implementation, this would materialize the canonical PlanDelta back + into the framework's internal PlanDelta representation after a round-trip + through adapters/coordinator. + """ + return plan_delta