docs(drift): draft from internal source

[pedromcunha]

Drafted from an internal source repo, requested by @dcompoze.

This PR was auto-generated by the reusable-docs-draft-pr workflow from a Claude-drafted update in the source repo. It is opened as a draft — please review, edit as needed, and mark ready for review before merging.

Review checklist

• Content matches the behavior shipped in the source PR
• No internal-only details (service names, file paths, unreleased names, security internals) leaked into the draft
• Conforms to CLAUDE.md style rules
• Cross-references and internal links resolve
• Any Needs human input items from the source comment are addressed

---

Generated by reusable-docs-draft-pr.yml in relayprotocol/agents-config.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
unevenlabs	🟢 Ready	View Preview	Oct 8, 2026, 3:29 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Claude finished @pedromcunha's task in 1m 8s —— View job

---

Review: PR #495 — Third-party oracle docs (status endpoint + mandatory API keys)

• Gather context
• Read diff of references/protocol/guides/third-party-oracle.mdx
• Check against CLAUDE.md style rules and positioning guidance
• Post review

The rewrite holds together. Every reference to the old rate limit (UNAUTHENTICATED_RATE_LIMIT_*, 429, "bypass the limit", the old API_KEYS warning) is gone from the page and from the rest of the repo. The auth, peering, deployment-sequence and checklist sections all agree with the new "key required" model. The new section uses ##/no deeper headings, keeps paragraphs to 3 sentences or fewer, and leaks no internal service names. I found no blocking errors, only a few gaps worth closing before merge.

1. Upgrading operators get no warning about the breaking change (medium) — lines 260, 336–344
This change breaks existing setups in two ways:

• An instance without API_KEYS no longer starts.
• Callers and peers that relied on unauthenticated access to /chains/v1 and the attestation routes now get 401.

The protocol line has no changelog source under §4.2, so nothing tells an upgrading operator about this. Per the §4.2 exception for migration details every reader must see, consider a one-line <Info> under ## Authentication. It should say that these routes used to be public and rate limited, now require a key, and that operators must hand peers keys before upgrading. Otherwise, flag it to whoever owns protocol release notes.
Fix this →

2. pass-through peer credentials now carry an unstated requirement (medium) — line 369
Every receiving oracle now rejects requests without a key it accepts. With pass-through, the original caller's key therefore has to appear in API_KEYS on every peer, or that peer returns 401 and gets skipped. This shows up as authentication-error in checkResult and as a possible quorum shortfall. Add one sentence saying so.

3. PEER_RESPONSE_MAX_BYTES is mentioned but never explained (low) — line 191
It shows up only in the peer-checks sentence. Add it to the optional env block and the "Notes" list (lines 249–263) with its default, the same way PEER_REQUEST_TIMEOUT_MS is listed.

4. The monitoring item reads as if both conditions must hold (low) — line 424
status: "partial" and oracleSigner: null suggests you should alert only when both are true. According to line 165, partial alone (a failed or slow signer lookup) is already the signal. Suggested wording: "GET /status/v1 reporting status: "partial" or a missing/unexpected oracleSigner."

5. Nits

• Line 13: "Relay Oracle … serves as: An operationally stateless oracle service" says "oracle" twice and repeats the "attests to onchain facts" sentence from the Overview (line 9). Something like "Relay Oracle is:" followed by the list would read better.
• Line 165: the quorum shape is given only for the no-allowlist case. A short example of the configured shape (e.g. { "signers": ["0x…"], "threshold": 2 }) would help readers check their config.
• Line 173 / 342: withReport=true on /lives/v1 is unauthenticated, and per this page it returns build/version information. That's probably intended, but confirm against the source PR that exposing build identifiers there without a key is deliberate.
• The removed text said API_KEYS "authorize the force option on solver fill and refund attestations". Every attestation route now needs a key, so this distinction may be gone. If force still has its own gating (e.g. a key scope), the page no longer says so.

Not checked: I couldn't see the upstream source PR, so I didn't verify field names, status values, or the fallback order against the implementation. I assumed they match the shipped code.
· Branch: docs-drift/src-2905baf98f-01132f3

[greptile-apps]

Confidence Score: 4/5

[Low impact] Updates documentation about the oracle service.

The PR appears safe to merge, with a non-blocking correction needed to the deployment order.

Findings

1.  Key setup comes too late ▶

Summary

Updates the third-party oracle guide with status reports, peer checks, and required API keys.

• Documents build information, peer results, and chain differences.
• Replaces public, rate-limited access guidance with authenticated access.
• The deployment steps should move key setup before startup and chain checks.

_{Reviews (1) · Last reviewed commit: "Fix up section name and reword initial p..." · Reviewed by Greptile}

[greptile-apps]

Key setup comes too late

The deployment sequence puts API key setup after deployment and chain checks. The new requirements say API_KEYS must contain at least one key before the oracle can start, and /chains/v1 also requires a key. Operators must jump ahead to complete the earlier steps. Move key setup before deployment so the sequence can be followed in order.