idea172-bevault-verifiable-best/AGENTS.md

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.