# ExProve SWARM Guidelines

Architecture overview
- Canonical primitives form the Covariant IR for cross-venue execution provenance:
  - LocalExecutionTask: per-instrument, per-venue planning unit
  - SharedMarketContext: privacy-safe, versioned market signals
  - PlanDelta: incremental routing/size/timing decisions with metadata
  - Attestation/AuditLog: cryptographic attestations and append-only logs
  - Graph-of-Contracts: adapters and data-contract schemas
- Edge-native solver: lightweight optimizer co-located with venue data to produce PlanDelta
- Delta-sync with deterministic replay for offline backtesting and regulatory review
- Governance ledger: cryptographic signing, policy hooks, optional cloud anchoring
- Adapters marketplace: plug-in venue adapters translating venue data into canonical IR

MVP plan (8–12 weeks)
- Phase 0: Skeleton protocol, 2 starter adapters, toy objective (VWAP-like), deterministic delta-sync
- Phase 1: Governance scaffolding, identity management, secure aggregation for SharedMarketContext
- Phase 2: Cross-venue demo in simulated env; publish ExProve SDK and minimal contract example
- Phase 3: Backtesting harness and deterministic replay; compliance-report generator

Deliverables
- Core data contracts: LocalExecutionTask, SharedMarketContext, PlanDelta, Attestation, AuditLog, Graph-of-Contracts
- Toy adapters (2 starters) and conformance harness
- Seed DSL for LocalExecutionTask/SharedMarketContext/PlanDelta
- Reference ExProve SDK (Python/C++ bindings) and transport layer

Testing and QA
- Lightweight conformance harness and toy adapters (end-to-end replay tests)
- Deterministic tests for PlanDelta generation
- Audit-ready logs and crypto tagging (signatures stubs for MVP)

Repository rules
- Use Python for core MVP; keep dependencies minimal
- Add test.sh that builds and runs tests; ensure python packaging compiles
- If you add external dependencies, update pyproject.toml and keep tests deterministic

Contributing
- Follow the existing coding style in this repo; keep changes minimal and well-scoped
- Add tests for any bug fixes or new primitives
- Update README with usage notes and contributor guidelines