# ArbSphere: Federated Cross-Exchange Equity Arbitrage (Prototype)

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.

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

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.