# BeVault: Architecture and Contribution Guide

Overview
- BeVault is a modular backbone enforcing and proving Best Execution across multiple equity venues.
- The MVP focuses on a Graph-of-Contracts (GoC) registry, two starter adapters, and deterministic delta-sync with signed deltas.

Tech Stack (Production-Ready)
- Language: Python 3.8+
- Core: lightweight dataclasses for LocalArbProblem, SharedSignals, HedgeDelta, AuditLog, PrivacyBudget
- Registry: GoCRegistry and GraphOfContracts with versioned adapters
- Adapters: PriceFeedAdapter, BrokerAdapter (starter)
- Crypto: HMAC-SHA256 based delta signing (pluggable key material)
- Data Contracts: toy DSL seeds as Python dataclasses
- Tests: pytest-based unit tests

Project Structure
- idea172_bevault_verifiable_best/
  - __init__.py
  - core.py
  - signing.py
  - registry.py
  - adapters/
    - __init__.py
    - price_feed.py
    - broker.py
- tests/
  - test_basic.py
- README.md
- AGENTS.md (this file)
- test.sh
- pyproject.toml
- READY_TO_PUBLISH (empty when ready)

How to contribute
- Start with the MVP: wire two adapters and ensure delta-signing and delta-sync are deterministic.
- Expand the GoC registry with new contracts/adapters following the toy DSL seeds.
- Ensure tests cover core contracts, registry operations, and adapter conformance checks.