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

Provenance Enhancements

• PlanDelta now includes extended provenance fields: version (IR schema version), nonce (replay protection), and signer (provenance/identity).
• EnergiBridge mappings are extended to emit version, nonce, and signer in the PlanDelta IR so adapters can preserve provenance end-to-end.
• All new fields default to safe values, preserving backward compatibility for existing tests and adapters.

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.