idea159-arbsphere-federated-cross/docs/arbsphere_mvp_contracts.md

ArbSphere MVP Contracts: Toy DSL Seeds and Canonical IR

This document provides small, self-contained seeds for ArbSphere primitives that can be used by adapters to bootstrap interoperability in a two-venue MVP. The seeds follow the CatOpt-inspired canonical IR mapping used by EnergiBridge-like bridges.

Primitives (DSL seeds)

• LocalArbProblemSeed

  • id: string
  • venue: string
  • asset_pair: string (e.g. "AAPL/MSFT")
  • target_misprice: float
  • max_exposure: float
  • latency_budget_ms: int

• SharedSignalsSeed

  • version: int
  • price_delta: float
  • cross_venue_corr: float
  • liquidity: float

• PlanDeltaSeed

  • actions: list of dicts with keys {venue_from, venue_to, instrument, size, time}
  • timestamp: ISO8601 string
  • delta_id: string
  • signer: string (optional)
  • signature: string (optional)

• DualVariablesSeed

  • multipliers: dict
  • version: int

• PrivacyBudgetSeed

  • limit: float
  • remaining: float
  • expiration: ISO8601 string

• AuditLogSeed

  • entries: list of AuditLogEntrySeed

• AuditLogEntrySeed

  • ts: ISO8601 string or numeric
  • event: string
  • details: dict
  • signature: string

Example: two-venue MVP seed composition

LocalArbProblemSeed: {
  id: "seed-venue-A-1",
  venue: "venue-A",
  asset_pair: "AAPL/MSFT",
  target_misprice: 0.5,
  max_exposure: 10000.0,
  latency_budget_ms: 50
}
SharedSignalsSeed: {
  version: 1,
  price_delta: 0.12,
  cross_venue_corr: 0.75,
  liquidity: 20000.0
}
PlanDeltaSeed: {
  actions: [ {venue_from: "venue-A", venue_to: "CROSS-VENUE", instrument: "AAPL/MSFT", size: 100, time: "2026-01-01T00:00:00Z"} ],
  timestamp: "2026-01-01T00:00:00Z",
  delta_id: "delta-001",
  signer: "arb-issuer",
  signature: "sig"
}

Usage guidance

• Adapters should map their vendor-specific data to these seeds before translation into the canonical IR.
• The seeds are intended to be minimal, deterministic, and extensible as more primitives are added.

Sanity checks

• Validate that LocalArbProblemSeed.asset_pair is two-tuple string when exported to IR.
• Ensure that PlanDeltaSeed.actions are deduplicated in downstream merges to support deterministic replay.