Centralize the shared BYOS specification - #1
Merged
jean-neiverth merged 8 commits intoAug 12, 2026
Conversation
VitePress on GitHub Pages, with mermaid for the settlement sequence diagrams and a local search index. Dead links fail the build: an ADR in an implementation repo that cites a section which no longer exists must break CI here rather than rot silently. scripts/gen-llms.ts emits llms.txt, llms-full.txt, and a raw markdown mirror of every page, so an agent fetching design-document.md gets markdown rather than a parsed-out article.
design-document.md is normative and monolithic, extracted from the live ADRs in byos-contracts and byos-service. Its "Citable sections" table is the interface that implementation-repo ADRs cite; anchors there are stable, and heading text may only be reworded in ways that preserve them. Section numbers are deliberately absent so inserting a section invalidates nothing. glossary.md merges the ~13 terms that byos-contracts/CONTEXT.md and byos-service/CONTEXT.md both defined, along with the "What BYOS is" paragraph and the Track A/B table that were byte-identical in each. Those files keep only what is local to them. The sub-solver guide carries sequence and gotchas only. Every field name, amount, and signature shape links into the design document or the OpenAPI document instead of being repeated.
…e implementation repos cow-solver-slashing-policy.md was byte-identical in three repos; solver-auctions.md and solver-cips.md in two. cow-fee-collection.md and the trampoline isolation proof lived only in byos-contracts despite both halves depending on them. Relative links that pointed at contract-side ADRs now point at design-document anchors. operations/slo-targets.md is the latency half of byos-service's metrics-reasoning.md. The cost and revenue half stays out: it carries bleu's internal dev rate, infra cost basis, and per-solver revenue comparables, which do not belong in an auditor- and sub-solver-facing repo.
…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.
…ysis-v2 docs: add overview, contracts reference, service architecture pages
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Risk: medium. Approved — Cursor Bugbot and Cursor Security Agent were not present after the initial check poll, so those signals were skipped; no applicable approval policy required human review. No reviewers assigned.
Sent by Cursor Approval Agent: Pull Request Router and Approver
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
BYOS documentation was spread across three repos with no owner.
cow-solver-slashing-policy.mdwas byte-identical in all three;solver-auctions.mdandsolver-cips.mdin two. BothCONTEXT.mdfiles defined the same ~13 domain terms, along with an identical "What BYOS is" paragraph and Track A/B risk table. Worse, one decision had two hand-maintained homes:byos-serviceADR-0003 says outright thatbyos-contractsADR-0004 is "a contract-scoped extract of the same decision". Those two have not drifted yet, which is the only reason this merge is mechanical rather than an adjudication, and that window will not stay open. Meanwhileorder-flow.mdlived in the contracts repo despite its first actor being the BYOS driver, and a TypeScript service now exists as a second consumer of everything the Rust one depends on.This repo becomes the single normative home for anything that constrains more than one implementation or that a reader outside bleu needs.
design-document.mdis that specification, extracted from the live ADRs; its "Citable sections" table is a stable anchor API that implementation-repo ADRs will cite instead of restating, so each ADR shrinks to the rationale only it owns. Section numbers are deliberately absent from headings, and slugs come from heading text rather than{#custom}syntax, because that syntax renders as literal text on GitHub and citations have to resolve both from the site and from thedocs/shared/submodule.glossary.mdtakes over the shared vocabulary; the reference docs, the isolation proof, and the SLO half ofmetrics-reasoning.mdmove in. The cost and revenue half of that file stays out, since it carries bleu's internal dev rate and per-solver revenue comparables that do not belong in an auditor-facing repo. Reviewers should look hardest at the implementation status table in the design document: those cells are inferred from the ADRs rather than read off the code, andbyos-servicemarked partial on escrow and penalties is the weakest claim. Nothing has changed in the three implementation repos yet; adding the submodule and trimming their ADRs is the follow-up.