diff --git a/README.md b/README.md index ae750d8..4bd65bd 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,44 @@ -ArbSphere - Federated Cross-Exchange Equity Arbitrage Primitives (Toy MVP) +# ArbSphere: Federated Cross-Exchange Equity Arbitrage (Prototype) -Overview -- Provides a minimal, test-driven prototype of canonical ArbSphere primitives: - - LocalArbProblem, SharedSignals, PlanDelta, DualVariables, AuditLog, PrivacyBudget -- A lightweight EnergiBridge-like IR mapping (arbsphere.ir.map_to_ir) -- A tiny ADMM-style coordinator (arbsphere.coordinator.admm_lite_step) -- A Graph-of-Contracts registry scaffold (arbsphere.go_registry.GoCRegistry) -- Toy adapters (price feed, broker) to bootstrap interoperability +ArbSphere is a lightweight, standards-driven prototype for federated cross-exchange equity arbitrage with privacy-preserving provenance and verifiable reproducibility. The repository includes a minimal canonical IR and an end-to-end two-venue demo to bootstrap interoperability across data feeds and execution adapters. -How to run tests -- Ensure Python 3.8+ is available -- Run: pytest -q -- (Optional) Run packaging check: python -m build +Key concepts (canonical primitives): +- LocalArbProblem: per-venue arbitrage task (asset pair, target mispricing, liquidity budget, latency budget) +- SharedSignals: aggregated signals across venues (price deltas, cross-venue correlations, liquidity, latency proxies) +- PlanDelta: incremental arbitrage actions (legs, sizes, timing) with deterministic identifiers for replay +- DualVariables, AuditLog, PrivacyBudget: governance/provenance extensions for auditable operation +- Graph-of-Contracts (GoC): registry of adapters and data schemas with per-message metadata to support replay/provenance -Notes -- This is a production-oriented scaffold focused on deterministic replay, auditable provenance, and interoperability. It is not a complete trading system. +Architecture overview +- ARBSphere primitives live in arbsphere/primitives.py and arbsphere/coordinator.py for the toy two-venue demo. +- A lightweight EnergiBridge (arbsphere/energi_bridge.py) translates primitives into a canonical IR for adapters. +- A small GoC registry (arbsphere/go_registry.py) tracks adapters and their metadata. +- A two-venue demo (arbsphere/two_venue_demo.py) wires a price-feed adapter and a broker adapter to demonstrate end-to-end operation. + +Getting started +- Run tests and packaging checks: + bash test.sh +- Run the two-venue demo: + python arbsphere/two_venue_demo.py +- Explore the IR mapping helper: + python -c "from arbsphere.ir import map_to_ir; from arbsphere.primitives import LocalArbProblem; lp = LocalArbProblem(asset_pair=('AAPL','USD'), target_mispricing=0.5, liquidity_budget=100000.0, latency_budget=0.2); print(map_to_ir(lp))" + +Extending ArbSphere +- The MVP is intentionally small: work in small, well-scoped steps. +- Extend the EnergiBridge with additional IR fields and versioning as new adapters are added. +- Expand the GoC registry to describe more adapters and their schemas. +- Add more sophisticated replay (CRDT-like delta merging) and cryptographic attestations for plan deltas. + +Foundations for the 8–12 week MVP plan are documented in the repository wiki/docs: +- docs/arbsphere_mvp_spec.md (toy two-venue MVP spec, contract example, and adapters) + +If you want, I can draft and implement a concrete toy two-venue MVP spec and a minimal arb contract to bootstrap ArbSphere interoperability across exchanges. + +For reference, the package is named and versioned as: +- Package: idea159-arbsphere-federated-cross +- Version: 0.1.0 + +Happy to adjust the scope or naming conventions to fit your team’s standards. + +--- +This README intentionally mirrors the project structure and provides a quick-start for new contributors. diff --git a/docs/arbsphere_mvp_spec.md b/docs/arbsphere_mvp_spec.md new file mode 100644 index 0000000..1427759 --- /dev/null +++ b/docs/arbsphere_mvp_spec.md @@ -0,0 +1,36 @@ +ArbSphere MVP Specification (Two-Venue, Toy Adapters) + +Purpose +- A canonical, privacy-preserving federated cross-exchange arbitrage prototype with deterministic replay, auditable provenance, and a lightweight cross-venue coordination layer. + +Core Primitives (canonical IR seeds) +- LocalArbProblem: asset_pair, target_mispricing, liquidity_budget, latency_budget +- SharedSignals: price deltas, cross-venue correlations, borrow/liquidity, latency proxies +- PlanDelta: incremental actions with legs, sizes, timestamps, delta_id +- DualVariables: shadow prices/risk multipliers +- PrivacyBudget: privacy budgets for signals +- AuditLog: governance/provenance events +- Graph-of-Contracts (GoC): registry of adapters and data schemas with per-message metadata (version, timestamp, nonce) + +Two-venue MVP wiring (8–12 weeks) +- Phase 0: protocol skeleton + 2 starter adapters (venue feed, broker) over TLS; ADMM-lite coordinator; end-to-end delta-sync with deterministic replay for toy hedges (delta-neutral spread). +- Phase 1: governance ledger scaffolding; identity management (DID/short-lived certs); secure aggregation defaults for SharedSignals; 2-adapter conformance harness. +- Phase 2: cross-domain demo in a simulated two-venue environment; publish ArbSphere SDK (Python/C++) and a minimal contract example; reference transport. +- Phase 3: hardware-in-the-loop latency tests; KPI dashboards for delta-merge latency, hedge convergence vs centralized baseline, adapter conformance, governance auditability. + +Data contracts seeds +- LocalArbProblem, SharedSignals, PlanDelta, DualVariables, AuditLog, PrivacyBudget; toyPair registry entry for 2 adapters. + +Security & governance +- Per-message crypto-tags; identity using DID or short-lived certs; secure aggregation; tamper-evident logs; optional cryptographic attestations on deltas. + +Risks & mitigations +- Data leakage risk mitigated by secure aggregation and privacy budgets; deterministic replay robust with hash-chains and clock-drift handling; auditability via governance logs anchored to a registry. + +Open questions for the group +- Two-venue pilot with synthetic feeds first, then live pilots? +- Open standard for EnergiBridge mapping? Minimal viable versioning scheme? +- Assessment of cross-domain adapters in NovaPlan/GridVerse style transports. + +Appendix +- MVP wiring details (Phase 0) and a skeleton contract example can be added here as the project progresses.