docs(drift): draft from internal source

[pedromcunha]

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

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 27, 2026, 6:45 AM

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
unevenlabs	🟡 Building	–	Jul 27, 2026, 6:45 AM

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

[github-actions]

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

---

Review: docs(drift): draft from internal source

• Read PR diff and changed files
• Check conformance to AGENTS.md style rules
• Verify cross-references and anchors resolve
• Post review

Overall this is a clean, well-scoped drift draft. Two new failReason enum members land in the right table on execution-errors.mdx, and the changelog entry follows the §4.5 format with newest-first ordering and bolded change-type leads. Nothing here looks internal-only or leaked. A few things to fix before merge.

---

1. on-chain should be onchain (blocking — style rule)

AGENTS.md §5 Terminology: onchain — one word, no hyphen. Two new occurrences:

• references/api/api_core_concepts/execution-errors.mdx:63 — "…was not included on-chain before Relay's retry…"
• references/api/changelog.mdx:8 — "…but never included on-chain before Relay's…"

The repo is 63 × onchain vs 4 × on-chain (all pre-existing drift), so the guide is clearly the intended convention.

Fix this →

2. New table rows are much longer than every other row in the table

execution-errors.mdx:62-63 are ~40 and ~50 words respectively, and row 63 is two sentences. Every other row in the file is a terse one-liner (longest existing is DESTINATION_TOKEN_TRANSFER_REJECTED at ~33 words). §2.7 asks for concise cells with long explanations moved to prose.

Suggested trims that keep the load-bearing facts:

| TRANSACTION_SUBMISSION_FAILED | The fill transaction could not be broadcast — the RPC or signer was unavailable, or the transaction was rejected before broadcast. No transaction hash exists. |
| TRANSACTION_NOT_INCLUDED | The fill transaction was broadcast and a hash was recorded, but it wasn't included onchain before Relay's retry and gas-bump window elapsed. The recorded hash may still confirm afterwards. |

3. Changelog **Added** paragraph is one ~90-word sentence

changelog.mdx:8 packs both new enum members into a single sentence with three parentheticals. §2.10 caps paragraphs at 2–3 sentences, and the directly analogous prior entry (2026-05-15 — More specific failReason values on request status, line 75) splits one sentence per enum member. Recommend matching that precedent — it reads much better and keeps the diff style-consistent with its neighbours.

4. Scope mismatch between **Added** and **Behavior change** (worth confirming against the source PR)

• **Added** (line 8) describes the two codes generally, as fill-transaction outcomes on all three surfaces.
• **Behavior change** (line 10) scopes the reclassification specifically to "gasless /execute failure rows".

If the new reasons are only emitted for gasless /execute fills, the execution-errors.mdx rows should say so (other Solana/Jupiter-specific rows in that table carry a parenthetical qualifier). If they're emitted for all fills, the behavior-change line is under-scoped and should drop the gasless framing. Right now a reader gets two different answers.

5. Anchor #transaction-construction--gas-errors — please verify on the preview

changelog.mdx:8 links to /references/api/api_core_concepts/execution-errors#transaction-construction--gas-errors. The double hyphen is what github-slugger produces for ### Transaction Construction & Gas Errors, so it's very likely right — but this is the only &-containing heading anchor in the repo, so there's no local precedent to confirm against. Worth one click on the preview before merge. (I couldn't fetch the preview from this job — network access wasn't granted.)

6. Nits

• Emphasis inconsistency — line 8 uses `TRANSACTION_SUBMISSION_FAILED` (bold + backticks) for enum values; the neighbouring 2026-05-15 and 2026-06-05 entries use plain backticks for the same kind of value. §2.9 reserves bold+backticks for prose references to parameters. Suggest plain backticks for consistency.
• Section fit — both new codes are broadcast/inclusion failures, not construction or gas failures, yet they sit under ### Transaction Construction & Gas Errors. Fine as a judgment call, but if more submission-lifecycle codes are coming, a dedicated ### Submission & Inclusion Errors section would age better.
• Pre-existing, adjacent to your hunk — changelog.mdx:16-17 is missing the blank line before ## 2026-07-09. Not yours, but it's one line above your entry if you want a free drive-by fix.

---

Nothing in items 2, 3, 5, or 6 is blocking. Item 1 is a straightforward style-guide fix and item 4 is a factual question only the source PR can settle.
• docs-drift/src-2856a1193e-50d9f51

[GiselleNessi]

Reviewed — both codes verified against the solver v3 schema and their assignment sites; descriptions are accurate, no internal-only details. Fixed two on-chain → onchain style-guide violations directly on the branch.

[github-actions]

Claude finished @GiselleNessi's task in 2m 6s —— View job

---

Re-review: docs(drift): draft from internal source

• Read PR diff and changed files (f26cf18)
• Check conformance to AGENTS.md style rules
• Verify cross-references and anchors resolve
• Post review

Re-reviewed at f26cf18. The blocking item is resolved — onchain is now correct in both new lines (execution-errors.mdx:63, changelog.mdx:8), and the four remaining on-chain occurrences are all pre-existing and outside this diff. Nothing else in the diff blocks merge.

Also noting @GiselleNessi's verification against the solver v3 schema and assignment sites, which settles the factual question I raised as item 4 last round. Below is the state of the rest, all optional.

---

Resolved

• ✅ Item 1 — on-chain → onchain. Fixed in f26cf18.
• ✅ Item 4 — scope of the two new reasons. Verified against the source schema by a human reviewer. On the accurate-as-written reading the two paragraphs are consistent: the enum members are returned on all three surfaces (**Added**), while the reclassification away from UNKNOWN only affected gasless /execute rows (**Behavior change**). If you want to close the door on the misreading, changelog.mdx:10 could open with "Previously, gasless /execute failure rows returned…" so the gasless qualifier clearly attaches to the old behavior rather than the new codes' scope. Purely cosmetic.

Correction to my earlier review

• Item 5 — the #transaction-construction--gas-errors anchor. I said there was no local precedent for an &-containing heading. That was wrong: there are 12 such headings in the repo, six of them in this very file (### Deposit & Validation Errors, ### Solver Capacity & Balance Errors, etc.). What's actually unprecedented is linking to one — this is the repo's only double-hyphen anchor link. github-slugger drops the & and keeps both surrounding spaces as hyphens, so transaction-construction--gas-errors is the correct slug and I'd treat this as fine. I still couldn't fetch the preview to confirm (network access not granted to this job), so one click on the preview link would make it certain.
• Item 2 — row length. Softening this. I compared against the wrong row: the longest existing description is ~25 words, not ~33, but BLOCKED_WALLET (line 25) is already a two-sentence row, so two-sentence cells have precedent in this table. The new rows (~38 and ~39 words) are still the longest in the file by a fair margin, so the §2.7 "keep cell descriptions concise" trim is still worth doing — but it's a preference, not a convention break.

Still open (non-blocking)

A. Trim the two new table cells — execution-errors.mdx:62-63. Suggested wording that keeps every load-bearing fact:

| TRANSACTION_SUBMISSION_FAILED | The fill transaction could not be broadcast — the RPC or signer was unavailable, or the transaction was rejected before broadcast. No transaction hash exists. |
| TRANSACTION_NOT_INCLUDED | The fill transaction was broadcast and a hash was recorded, but it wasn't included onchain before Relay's retry and gas-bump window elapsed. The recorded hash may still confirm afterwards. |

Fix this →

B. Split the **Added** sentence — changelog.mdx:8 is still one ~90-word sentence with three parentheticals. §2.10 caps paragraphs at 2–3 sentences, and the directly analogous prior entry (2026-05-15 — More specific failReason values on request status, line 75) uses one sentence per enum member. Matching that precedent reads better and keeps the diff consistent with its neighbours.

Fix this →

C. Emphasis nit — changelog.mdx:8 uses `TRANSACTION_SUBMISSION_FAILED` (bold + backticks) for enum values; the 2026-05-15 and 2026-06-05 entries use plain backticks for the same kind of value, and §2.9 reserves bold+backticks for prose references to parameters. Plain backticks would be consistent. (Covered by the fix link above.)

D. Section fit — both new codes are broadcast/inclusion failures rather than construction or gas failures, yet they sit under ### Transaction Construction & Gas Errors. Fine as a judgment call; if more submission-lifecycle codes are coming, a dedicated ### Submission & Inclusion Errors section would age better.

E. Free drive-by (pre-existing) — changelog.mdx:16-17 is missing the blank line before ## 2026-07-09, one line below your entry. Not introduced here, still unfixed.

---

Verdict: ready to merge as-is. A–E are polish; B is the one I'd most recommend taking since it has a direct precedent two entries down the same file.
• docs-drift/src-2856a1193e-50d9f51

[GiselleNessi]

Verified both codes against the solver v3 schema and assignment sites; style fixes pushed. LGTM.