# ArbSphere Federated Cross (Toy)

This repository provides a minimal, test-focused Python package that defines
the canonical ArbSphere primitives and a deterministic ADMM-like step function
used by unit tests. It serves as a starting point for a more comprehensive
federated arbitrage prototype with privacy-preserving provenance and auditability.

What this repo delivers today
- Core primitives: LocalArbProblem and SharedSignals, plus a simple PlanDelta
  generated by admm_step, suitable for deterministic testing and replay.
- A lightweight translator: EnergiBridge, which serializes ArbSphere primitives into
  a canonical IR for adapters and cross-venue bridges.
- A small Graph-of-Contracts registry (GoC) and a basic registry for adapters.
- Packaging scaffold with a test suite (pytest) and a packaging check (python -m build).

Roadmap (high level)
- Phase 0: protocol skeleton and two starter adapters with a lightweight ADMM-lite
  coordinator. Demonstrate a simple cross-venue mispricing capture with bounded
  plan feasibility and deterministic replay.
- Phase 1: governance ledger scaffold, identity management (DID/short-lived certs),
  and secure aggregation for SharedSignals.
- Phase 2: end-to-end cross-domain demo in a two-venue simulation, SDK bindings (Python/C++),
  and a minimal contract example.
- Phase 3: latency-aware backtesting harness, performance dashboards, and auditability metrics.

Interoperability and privacy
- Canonical bridge mapping ArbSphere primitives to a vendor-agnostic IR (EnergiBridge).
- Protobuf/JSON-like IR is designed to be adapter-friendly, with per-message metadata
  for replay protection and auditability.
- A lightweight Graph-of-Contracts registry to describe adapters, versions, and endpoints.

Testing and packaging
- Run tests with: bash test.sh
- Packaging verification via: python3 -m build
- The repository is configured to be production-ready enough for CI checks while
  remaining a clean, educational scaffold for exploring federated arbitration ideas.

If helpful, I can draft toy adapter blueprints, an EnergiBridge mapping for ArbSphere,
and a minimal two-venue toy contract to bootstrap interoperability.

Two-Venue MVP Orchestrator
- A small Python script (orchestrator.py) wired in idea159_arbsphere_federated_cross/ that demonstrates a complete two-venue flow:
  - Build two LocalArbProblem instances for two venues
  - Run admm_step against each to produce PlanDelta
  - Deterministically merge deltas via EnergiBridge.merge_deltas
  - Serialize to canonical IR with EnergiBridge.to_ir
  - Route the merged delta through a toy broker adapter to simulate execution
- This serves as a practical, end-to-end demonstration of ArbSphere interoperability across two exchanges and a minimal governance/traceable flow.