50 lines
3.2 KiB
Markdown
50 lines
3.2 KiB
Markdown
# 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.
|