Skip to content

docs: add overview, contracts reference, service architecture pages - #2

Merged
jean-neiverth merged 4 commits into
bleu:pedro/cow-1119-refactor-design-document-subsolver-guidefrom
jean-neiverth:pedro/cow-1119-docs-gap-analysis-v2
Aug 12, 2026
Merged

docs: add overview, contracts reference, service architecture pages#2
jean-neiverth merged 4 commits into
bleu:pedro/cow-1119-refactor-design-document-subsolver-guidefrom
jean-neiverth:pedro/cow-1119-docs-gap-analysis-v2

Conversation

@jean-neiverth

@jean-neiverth jean-neiverth commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Summary

  • New: overview.md — "What is BYOS" page with problem statement (solver onboarding barrier with bonding pool numbers), before/after contrast, how BYOS works at a high level, revenue model, consolidated rejection reasons table, and slashing policy summary
  • New: contracts.md — Contracts reference with Escrow/Trampoline/TrampolineFactory interfaces (functions, events, errors), how BYOS interacts with each contract, and key design decisions consolidated from contracts ADRs
  • New: service.md — Service architecture with two-listener model, async validation loop, proposal lifecycle, scoring, gas cut, persistence model, and key design decisions consolidated from service ADRs
  • Enhanced: sub-solver integration guide — Added explicit responsibility framing ("you ARE / you are NOT responsible for"), API endpoint summary table, and TypeScript reference implementation alongside the Rust one
  • Updated vitepress sidebar/nav and README entry points

Context

Gap analysis against expected documentation coverage identified these missing areas:

  1. No accessible "what is BYOS" overview for newcomers
  2. No dedicated contracts or service reference pages (details were embedded in the 72KB design document)
  3. Sub-solver guide lacked explicit role framing, API summary, and TS example reference
  4. Design decisions from implementation repo ADRs were not surfaced in the shared docs

…nd enhance subsolver guide

- Add overview.md: problem statement (solver onboarding barrier), before/after
  contrast, how BYOS works, revenue model, consolidated rejection reasons,
  slashing policy summary
- Add contracts.md: Escrow/Trampoline/TrampolineFactory interfaces (functions,
  events, errors), how BYOS interacts with each, key design decisions from
  contracts ADRs
- Add service.md: two-listener model, async validation loop, proposal lifecycle,
  scoring, gas cut, persistence model, key design decisions from service ADRs
- Enhance sub-solver integration guide: add explicit responsibility framing,
  API endpoint summary table, TypeScript reference implementation
- Update vitepress sidebar/nav and README entry points
Cut triads, contrastive "X, not Y" padding, self-defending justifications,
narrative flourishes, and unnecessary qualifiers. No facts removed.
@jean-neiverth
jean-neiverth marked this pull request as ready for review August 12, 2026 14:26
@jean-neiverth
jean-neiverth merged commit 7eff209 into bleu:pedro/cow-1119-refactor-design-document-subsolver-guide Aug 12, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant