Skip to content

docs: correct the rate limiting description for the shipped design - #7

Merged
jean-neiverth merged 4 commits into
mainfrom
pedro/cow-1128-rate-limiting
Aug 21, 2026
Merged

jean-neiverth merged 4 commits into
mainfrom
pedro/cow-1128-rate-limiting

Conversation

@yvesfracari

@yvesfracari yvesfracari commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor

Four corrections to the rate limiting description, from implementing COW-1128 in bleu/byos-service-ts (PR #49). Each is a place where the shipped design and the document disagree, and in each case the document is the one that needs to move.

The document said signers below the minimum escrow are "rejected outright". The service cannot do that: it cannot distinguish a never-seen address from an empty one without a chain read on the request path, which the same paragraph forbids. So an unknown address is admitted at the lowest tier and only a known-underfunded one is rejected. Rejecting on absence would lock out every new sub-solver on its first request. The reject-early pipeline also attributed the IP filter to the request path; it belongs at the edge, where a rejected request costs no socket, no ecrecover, and no connection-pool slot — but only while the origin is unreachable directly, otherwise the forwarded client-IP header is attacker-controlled and anything keyed on it is poisoned. That caveat is now stated rather than assumed, since it is the load-bearing precondition for the whole layer.

The floor gate is also scoped to submission, which came out of reviewing the implementation. Effective escrow balance reads as zero from the moment a sub-solver requests a withdrawal, so a gate on every verb left it unable to cancel — or even see — the proposals it still had live, while they stayed live until they expired. Refusing a cancellation is the wrong direction: it is the action that reduces exposure for both sides. The design document's paragraph and pipeline table, the overview's rejection table, and the integration guide's error table all said or implied otherwise.

The overview's synchronous-rejection table gains the escrow floor gate, and the integration guide gains a section on 429, 503 and Retry-After, plus rows in its error table. The guide is explicit that the reference clients ignore Retry-After and that this is a limitation of the examples rather than a pattern to copy.

Once this merges, byos-service-ts bumps its submodule pointer.

Three fixes from implementing COW-1128.

An unknown address is admitted at the lowest tier, not rejected: the
service cannot distinguish a never-seen address from an empty one, and
rejecting on absence would lock out every new sub-solver.

The per-IP filter belongs to the edge, not the request path. A request
rejected there costs no socket, no ecrecover, and no connection-pool
slot — but only if the origin is unreachable directly, otherwise the
forwarded client-IP header is attacker-controlled.

The synchronous rejection table gains the escrow floor gate, and the
integration guide gains 429 and 503 semantics with Retry-After.
@linear-code

linear-code Bot commented Aug 18, 2026

Copy link
Copy Markdown

COW-1128

yvesfracari and others added 3 commits August 18, 2026 17:47
Review of the implementation moved the gate to POST only. Effective escrow
balance reads as zero from the moment a sub-solver requests a withdrawal,
so a gate on every verb left it unable to cancel — or even see — the
proposals it still had live, while they stayed live until they expired.
Refusing a cancellation is the wrong direction: it is the action that
reduces exposure for both sides.

The design document's rate limiting paragraph and pipeline table, the
overview's synchronous-rejection table, and the integration guide's error
table and rate-limit section all said or implied the gate applies
everywhere.
Resolved conflict in overview.md by accepting main's navigation-page
structure. The substantive rate limiting and escrow floor gate corrections
from this branch (95e712b, 4e78a17) landed cleanly in design-document.md
and guides/sub-solver-integration.md via auto-merge.
The consolidated 'why proposals get discarded' table was dropped when
overview.md was refactored into a navigation page. Restore it as a
subsection of the proposal lifecycle, including the escrow floor gate
row (submission-only) added on this branch.
@jean-neiverth
jean-neiverth merged commit d93621b into main Aug 21, 2026
3 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.

2 participants