docs(routing): document optimistic provider queue (#1013)

[chibie]

Documents the ranked provider queue resolved at order creation, from paycrest/aggregator#1013.

Important

Do not merge before aggregator#1013 merges. That PR is still open. Every literal "3" in these docs tracks utils.DefaultProviderQueueSize, and the validation error strings are fmt.Sprintf'd from it — if the constant or any wording changes before merge, these tables drift silently. Worth a re-diff against the merged SHA.

What changed

Specs

• openapi-v2.yaml — new limit query param on the rates path (integer 1–3, default 3); V2RateQuoteSide.providerIds rewritten for ranked semantics, and rate now states it belongs to providerIds[0]; providerIds added to V2FiatDestination; third request example showing a queue passed through from a quote. Also filled in the missing description on V2CryptoDestination.providerId while in there.
• openapi-v1.yaml — providerIds on PaymentOrderRecipient. v1 rates left untouched: a scalar data cannot carry a ranked list.

Prose

• api-reference/general/get-token-rate.mdx — limit row and example, ranked response table + 3-element sample, new ### The provider queue section under Rate resolution.
• implementation-guides/sender-api-integration.mdx — new ### Pin a provider queue with the rules table and all seven verbatim 400 messages; prefetch note and JS/Python samples now pull providerIds.
• implementation-guides/smart-contract-interaction.mdx — new ### Routing fields plus a <Warning> on the tightened message-hash budget.
• resources/troubleshooting.mdx, api-reference/errors.mdx, resources/changelog.mdx.

No docs.json change — no new pages, matching the precedent of #15 and #21.

Notes for reviewers

The byte-budget change is the one integrators will actually feel. Everything else here is additive. But the recipient encryption preflight now reserves room for a full 3-provider queue on every order — including orders that never send providerIds, because one may be resolved onto the order and rides in the message hash at gateway submit. That leaves ~49 fewer bytes (~41 when pinning a providerId) inside the 500-byte cap for accountIdentifier + accountName + memo + metadata. A payload that passed yesterday can start returning 400 "Recipient data too large for encryption" with no client-side change. It gets a <Warning>, a troubleshooting entry, and a Behavior change: lead in the changelog — soften that framing here if it reads too loud.

providerIds is marked writeOnly in both specs. The field is accepted on create but no response builder ever populates it — orders and webhooks return only the singular assigned providerId. Without writeOnly the generated playground would show it in create/GET/webhook response examples, which would be wrong. Note V2FiatDestination is $ref'd from three response schemas, and v1's PaymentOrderRecipient is reachable from a v1 GET response, so this applies to both.

Three places where the docs deliberately say something non-obvious:

• Queue exhaustion is not an immediate refund — fallback assignment runs first, then the refund window. "3 tries then refund" is the natural wrong assumption, so it's stated explicitly in four places.
• OTC quotes still return exactly one providerIds entry, same as pinned quotes.
• An unusable queue inside an onchain message hash is dropped silently and the order routes as unpinned — no onchain rejection, no error webhook. Called out so onchain senders know to validate against a quote before encrypting.

Onramp is excluded throughout: V2CryptoDestination accepts only the singular providerId, and an onramp providerIds is silently ignored by binding.

Verification

• Both specs parse; redocly lint findings are byte-identical to main (19 errors / 65 warnings, all pre-existing) — nothing new introduced.
• mint broken-links → no broken links found, including the three new cross-page anchors.
• Not yet verified against a running API — the feature isn't deployed. Once aggregator#1013 hits staging, worth confirming ?limit=0 / ?limit=4 return the documented 400 string verbatim, and that create/GET responses genuinely omit providerIds.

🤖 Generated with Claude Code