docs(drift): draft from internal source

[pedromcunha]

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

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 (UTC)
unevenlabs	🟢 Ready	View Preview	Jul 22, 2026, 7:27 PM

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

[github-actions]

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

---

Code review — PR #374

• Read PR diff
• Check style-guide conformance (AGENTS.md)
• Verify cross-references / links resolve
• Check for internal-only leakage
• Post review

Two files, +8/−1. The changelog entry is well-written and the new INVALID_RECIPIENT row is alphabetically placed. The link to /references/api/api_core_concepts/handling-errors resolves. Four things worth addressing before merge, one of them a correctness regression on an existing row.

---

1. INVALID_ADDRESS description is now wrong for the user case

references/api/api_core_concepts/handling-errors.mdx:22

-| `INVALID_ADDRESS` | The provided user address is not valid. |
+| `INVALID_ADDRESS` | The provided user or recipient address is not valid for the target chain. |

The row broadened to cover recipient (correct — that's what shipped), but …not valid for the target chain is only true of the recipient. user is an origin-chain address, so for the pre-existing failure mode this row now states the wrong chain. Suggest dropping the chain qualifier or making it relative:

The provided user or recipient address is not a valid address for the chain it applies to.

Fix this →

2. Changelog entry labels a reclassification as **Added**

references/api/changelog.mdx:8

The entry itself says "Previously these requests surfaced as DESTINATION_TX_FAILED after simulation." — so for anyone switching on errorCode, this is an error-code change on requests that already failed, not purely an addition. The page already has precedent for exactly this shape at changelog.mdx:43-45 (2026-06-05, upstream RPC failures moved off DESTINATION_TX_FAILED), and that one is filed under **Behavior change**.

Suggest splitting: **Added** for the new INVALID_RECIPIENT code, **Behavior change** for the reclassification away from DESTINATION_TX_FAILED. That also fixes issue #3 below for free.

Fix this →

3. AGENTS.md §2.10 — paragraph length

references/api/changelog.mdx:8 is six sentences in one block, the longest paragraph on the page (nearest neighbours run 4–5, so there's some existing drift, but this one is over). The split in #2 resolves it.

4. The DESTINATION_TX_FAILED message change isn't reflected on the errors page

references/api/changelog.mdx:10 documents a new, more specific message for the blocked-recipient case, but handling-errors.mdx still carries only the generic form:

• handling-errors.mdx:55 — DESTINATION_TX_FAILED → "The relay transaction reverted on the destination chain."
• handling-errors.mdx:83-91 — the example response still shows "message": "Destination transaction failed".

AGENTS.md §4.4 says an observable behavior change updates the relevant page's prose and gets a changelog entry; right now only the changelog has it. A reader hitting the new message on the errors page has no way to connect it back. A sentence under the Unexpected Errors table, or a second example response, would close the loop.

Fix this →

---

Nits

• handling-errors.mdx:27 — "The provided recipient resolves to a supported token contract and cannot receive funds." reads as two ANDed conditions, and "resolves to" is doing odd work for what is just "is". Consider: "The provided recipient is a known token contract address, which cannot receive funds. Use a wallet address."
• changelog.mdx:10 — "blocklisted" vs. "blacklisted" used on handling-errors.mdx:36 (SANCTIONED_WALLET_ADDRESS). Pick one for consistency across the two pages.
• changelog.mdx:8 — "the implicit recipient = user path is not revalidated" is phrased from the implementation's point of view. The preceding clause ("Requests that omit recipient are unaffected") already says everything an integrator needs.
• Pre-existing, not from this PR: changelog.mdx:16-17 is missing a blank line before the ## 2026-07-09 heading. Renders fine under CommonMark, but it's inconsistent with the rest of the file — easy drive-by if you're touching this file anyway.

Checks that passed

• Internal link /references/api/api_core_concepts/handling-errors resolves.
• No internal-only leakage found — no service names, repo paths, or unreleased naming. POST /quote, POST /quote/v2, errorCode, and recipient are all public surface.
• INVALID_RECIPIENT inserted in correct alphabetical position; no other page in the repo enumerates error codes, so no third surface needs updating.
• Newest-first changelog ordering preserved; frontmatter unchanged and conformant.
  • branch docs-drift/src-d9b76a2df4-96d2f94

[github-actions]

Claude finished @pedromcunha's task in 2m 11s —— View job

---

Code Review: PR #374

• Gather context (diff, changed files, style guide)
• Review handling-errors.mdx changes
• Review changelog.mdx entry
• Check style-guide conformance (AGENTS.md)
• Verify cross-references resolve
• Post review

---

Small, well-scoped drift PR. The changelog format matches existing entries, INVALID_RECIPIENT is placed correctly in the alphabetical table, the link target resolves, and I found no internal-only details leaked (no service names, file paths, or unreleased identifiers). Five things worth fixing before merge, ordered by impact.

1. INVALID_ADDRESS — "target chain" is both off-vocabulary and wrong for user

references/api/api_core_concepts/handling-errors.mdx:22

| `INVALID_ADDRESS` | The provided user or recipient address is not valid for the target chain. |

Two problems:

• "target chain" isn't the term these docs use. It appears nowhere else under references/api/ — the only other uses are in references/protocol/ for withdrawal-proof destinations. The API docs say "destination chain" consistently (including line 17 and line 55 of this same page), and this PR's own changelog entry says "destination chain".
• It's inaccurate for the case the row just expanded to cover. The row now claims both user and recipient, but user is an origin-chain address. "not valid for the target chain" is wrong for half of what it now describes.

Suggested: The provided userorrecipient address is not a valid address for its chain.

Fix this →

2. The DESTINATION_TX_FAILED message change has no counterpart on the page it links to

references/api/changelog.mdx:10 documents a new user-visible message string, but handling-errors.mdx is untouched for that case:

• Line 55 still reads only The relay transaction reverted on the destination chain.
• The Destination Transaction Failed example (lines 83–91) still shows "message": "Destination transaction failed".

A reader following the changelog's "See [Handling Quote Errors]" link lands on a page that doesn't mention the recipient-blocked case at all. AGENTS.md §4.4 is explicit here: when a change alters observable behavior (error shape included), update the relevant page's prose and add a changelog entry — this PR did only the latter. Adding a clause to the line 55 description, or a second example response, would close the loop.

Fix this →

3. "blocklisted" collides with Relay's compliance-blocklist terminology

references/api/changelog.mdx:10 — "when a blocklisted wallet recipient reaches destination simulation…"

In this repo "blocklist" specifically means Relay's internal compliance/sanctions blocklist (security/compliance.mdx:12, solutions/payment-service-providers.mdx:40), which surfaces as SANCTIONED_WALLET_ADDRESS — a completely different error path. The token-contract-level deny list is called a "blacklist" here (references/api/api_core_concepts/execution-errors.mdx:81). As written, a reader can reasonably read this entry as being about sanctions screening.

Since the sentence goes on to say "blocked by the token contract" anyway, the adjective is doing no work — consider "when the destination token contract rejects a transfer to the recipient".

4. "Previously these requests…" has a dangling antecedent

references/api/changelog.mdx:8, sentence order:

…Requests that omit recipient are unaffected — the implicit recipient = user path is not revalidated. Previously these requests surfaced as DESTINATION_TX_FAILED after simulation.

"these requests" now reads as the omitted-recipient requests described immediately before, which is the opposite of the intent. Move the "Previously…" sentence up so it sits directly after the two new-error-code sentences, and let the omit-recipient carve-out close the paragraph.

While you're there: "the implicit recipient = user path is not revalidated" is implementation-flavored, and "Requests that omit recipient are unaffected" already conveys everything an integrator needs.

5. INVALID_RECIPIENT description joins a condition and its consequence with "and"

references/api/api_core_concepts/handling-errors.mdx:27

The provided recipient resolves to a supported token contract and cannot receive funds.

The second clause is the reason the request failed, not a second condition to satisfy — as written it scans as two independent requirements. "resolves to" is also vaguer than needed. Suggested: The provided recipient is a supported token contract, which cannot receive funds. Use a wallet address.

Minor / optional

• Two ## 2026-07-22 headings. §4.5 describes one ## per date carrying a short summary; the file now has two same-date sections. Newest-first ordering still holds, so this is cosmetic — merging into the existing 2026-07-22 entry would be tidier.
• Paragraph length (§2.10). The **Added** paragraph is six sentences / ~110 words, the longest in the file. Existing entries also run long so this matches local precedent, but splitting the INVALID_ADDRESS and INVALID_RECIPIENT cases into a bullet pair would read better.

Nothing here is blocking correctness of the API description itself — items 1 and 2 are the two I'd want addressed before this leaves draft. I reviewed only; no changes committed.
· branch docs-drift/src-d9b76a2df4-96d2f94

[GiselleNessi]

Reviewed — INVALID_RECIPIENT verified in solver (error-codes.ts, thrown from validateQuote.ts), the sharpened INVALID_ADDRESS description matches the new validation behavior, and the changelog entries are accurate. LGTM.

[GiselleNessi]

Verified INVALID_RECIPIENT and the INVALID_ADDRESS description against solver. LGTM.

[github-actions]

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

---

Code review — PR #374

• Read PR diff
• Read changed files in full context
• Check style-guide conformance (AGENTS.md)
• Verify cross-references / links resolve
• Check for internal-only leakage
• Post review

Two files, +8/−1. The changelog entry format matches the surrounding entries, INVALID_RECIPIENT is placed correctly in the alphabetical table, the link to /references/api/api_core_concepts/handling-errors resolves, and I found no internal-only leakage. INVALID_RECIPIENT and the INVALID_ADDRESS behavior were already verified against solver by @GiselleNessi, so I've scoped this to the docs themselves.

One real gap against AGENTS.md §4.4, plus terminology and structure items.

---

1. The DESTINATION_TX_FAILED message change lands only in the changelog

references/api/changelog.mdx:16 documents a new user-visible message string, but handling-errors.mdx — the page that entry links to — is untouched for that case:

• handling-errors.mdx:55 still reads only The relay transaction reverted on the destination chain.
• The Destination Transaction Failed example (lines 83–91) still shows "message": "Destination transaction failed".

AGENTS.md §4.4 is explicit: an observable behavior change (error shape included) updates the relevant page's prose and gets a changelog entry. This PR did only the latter, so a reader who hits Recipient cannot receive this token (blocked by the token contract) in production has no page that explains it. A clause on line 55 or a second example response closes the loop.

Fix this →

Related, and worth a thought while you're there: the recipient-blocked case is user-actionable ("Try a different recipient address"), but it sits under Unexpected Errors, which the page introduces as "infrastructure or downstream failures and are not common" (line 51). If integrators are now expected to surface this to users, the framing on that section undersells it.

2. INVALID_ADDRESS — "target chain" isn't this section's vocabulary

references/api/api_core_concepts/handling-errors.mdx:22

"target chain" appears nowhere else under references/api/ — the only uses in the repo are in references/protocol/ for withdrawal-proof destinations (for-solvers.mdx:43, hub.mdx:74, allocator.mdx:64). The API docs say destination chain consistently, including lines 17 and 55 of this same page and this PR's own changelog entry at changelog.mdx:14.

It's also imprecise for the half of the row that already existed: user is generally the origin-side depositor, so "not valid for the target chain" doesn't describe that failure mode. Suggested wording avoids introducing a chain term at all:

The provided user or recipient address is not a valid address for the chain it applies to.

Fix this →

3. "blocklisted" collides with Relay's compliance-blocklist terminology

references/api/changelog.mdx:16 — "when a blocklisted wallet recipient reaches destination simulation…"

In this repo "blocklist" means specifically Relay's compliance/sanctions blocklist (security/compliance.mdx:12, security/unsupported-exchanges.mdx:35, solutions/payment-service-providers.mdx:40), which surfaces as SANCTIONED_WALLET_ADDRESS — an entirely different error path. The token-contract-level deny list is called a blacklist here (handling-errors.mdx:36, execution-errors.mdx:83). As written, this entry reads as being about sanctions screening.

The sentence goes on to say "blocked by the token contract" anyway, so the adjective is doing no work — consider "when the destination token contract rejects a transfer to the recipient".

4. The **Added** block also carries a reclassification

references/api/changelog.mdx:14 ends with "Previously these requests surfaced as DESTINATION_TX_FAILED after simulation." For anyone switching on errorCode, that's an error-code change on requests that already failed — not purely an addition. The page has precedent for exactly this shape at changelog.mdx:49-51 (2026-06-05, upstream RPC failures moved off DESTINATION_TX_FAILED), filed under **Behavior change**.

Splitting into **Added** (the new INVALID_RECIPIENT code) and **Behavior change** (quote-time rejection replacing post-simulation DESTINATION_TX_FAILED) also fixes items 5 and 6 below.

Fix this →

5. "Previously these requests…" has a dangling antecedent

references/api/changelog.mdx:14, sentence order:

…Requests that omit recipient are unaffected — the implicit recipient = user path is not revalidated. Previously these requests surfaced as DESTINATION_TX_FAILED after simulation.

"these requests" now attaches to the omitted-recipient requests described immediately before, which is the opposite of the intent. Move the "Previously…" sentence up so it follows the two new-error-code sentences, and let the omit-recipient carve-out close the paragraph.

Also: "the implicit recipient = user path is not revalidated" is implementation-flavored — "Requests that omit recipient are unaffected" already tells an integrator everything they need.

6. AGENTS.md §2.10 — paragraph length

changelog.mdx:14 is six sentences / ~110 words, the longest paragraph on the page. Neighbours run 4–5 sentences, so there is some existing drift, but this one is over. The split in #4 resolves it.

---

Nits

• handling-errors.mdx:27 — "The provided recipient resolves to a supported token contract and cannot receive funds" ANDs a condition with its consequence, so it scans as two independent requirements. "resolves to" is also vaguer than needed. Consider: "The provided recipient is a supported token contract, which cannot receive funds. Use a wallet address."
• Two ## 2026-07-22 headings. §4.5 describes one ## per date carrying a short summary; the file now has two same-date sections. Newest-first ordering still holds, so this is cosmetic — folding into the existing 2026-07-22 entry would be tidier.
• Pre-existing, not from this PR: changelog.mdx:22-23 is missing a blank line before the ## 2026-07-09 heading. Renders fine, but it's inconsistent with the rest of the file — easy drive-by while you're in here.

Checks that passed

• Internal link /references/api/api_core_concepts/handling-errors resolves.
• No internal-only leakage — no service names, repo paths, or unreleased naming. POST /quote, POST /quote/v2, errorCode, and recipient are all public surface.
• INVALID_RECIPIENT inserted in correct alphabetical position; no other page in the repo enumerates quote error codes, so no third surface needs updating.
• Newest-first changelog ordering preserved; frontmatter unchanged and conformant to §2.1.

Items 1 and 2 are the ones I'd want addressed before this leaves draft. I reviewed only — no changes committed.
· branch docs-drift/src-d9b76a2df4-96d2f94