Rewrite protocol docs: add Relay Chain, Allocator, Mermaid diagrams, …

[ptrwtts]

Complete rewrite of the Settlement Protocol documentation section:

• Add Relay Chain documentation (Chain ID 537713, Sovereign Stack, Celestia DA)
• Add Allocator component docs (MPC chain signatures, Payload Builders)
• Restructure from flat component pages to narrative-driven architecture
• Add comprehensive flow walkthroughs (Execution, Settlement, Withdrawal, Revert)
• Add 8 inline Mermaid sequence diagrams with interactive zoom/pan
• Add Design Principles and Security & Audits pages
• Add solver and app integration guides
• Consolidate contract references and addresses
• Separate Vaults as distinct protocol section
• Add 13 URL redirects for old pages
• Delete 8 obsolete files

[clemsos]

some small comments but LG !

[julien51]

Suggested change

	The Allocator is the component responsible for authorizing withdrawals from [Depository](/references/protocol/components/depository) contracts. When a solver wants to claim funds they've earned by filling orders, the Allocator verifies their [Hub](/references/protocol/components/hub) balance and generates a cryptographic proof that the Depository will accept.
	The Allocator is the component responsible for authorizing withdrawals from [Depository](/references/protocol/components/depository). When a solver wants to claim funds they've earned by filling orders, the Allocator verifies their [Hub](/references/protocol/components/hub) balance and generates a cryptographic proof that the Depository will accept.

[ptrwtts]

I think we need a consistent terminology for the two types of depositories. How about "Contract Depository" and "Wallet Depository". We can explain this on the in-depth Depository page, but elsewhere can just use the term "Depository" to describe both

[github-actions]

Claude finished @julien51's task in 2m 23s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Review documentation structure and navigation
• Review all component and guide pages for accuracy and style
• Check previously flagged items
• Post final review

---

Excellent work — this is a major improvement over the previous flat structure. The narrative-driven architecture with component pages, Mermaid sequence diagrams, and clear flow walkthroughs is well-organized and thorough. Nearly all previous review feedback has been addressed.

Previously Flagged Items — Status

All critical items from prior reviews are resolved:

• Duplicate text blocks in depository/oracle/hub ✅
• refunds.mdx deleted ✅
• ERC20View added to relay-chain.mdx ✅
• DepositAddressFactory / DepositAddress naming ✅
• Security Council table expanded ✅
• Security Council "cannot:" wording and trailing sentence ✅
• Sui Payload Builder removed from allocator.mdx ✅
• Zellic added to depository.mdx and security.mdx ✅
• Bug bounty link → /security/bounties ✅
• Repo names in security.mdx corrected ✅
• H1 → H2 in contract reference pages ✅
• Allocator correctly noted as Aurora ✅

---

One Outstanding Item

references/protocol/guides/for-apps.mdx:52-58 — @julien51 flagged twice (and marked as "important") that integrators need guidance on finding the settlement transaction via the intent address. The current text (lines 52-58) mentions the Explorer and uses orderId as a correlation key, but doesn't explain the intent address concept — how to derive it from the orderId and look it up on the Relay Chain Explorer to see deposit, fill, and settlement attestation activity for a specific order.

Lines 60-80 describe the order address derivation (from chainId, depositor, timestamp, depositId), which is a different concept. The intent address derivation from orderId that @julien51 requested is still missing.

Fix this →

---

Minor Nits

• references/protocol/how-it-works.mdx:2 — @ptrwtts agreed the filename should be renamed to match the "Architecture" title (or vice versa), with a redirect. Still how-it-works.mdx with title "Architecture". Fine as a follow-up.

• references/protocol/components/deposit-addresses.mdx:11 — Minor grammar: "a stateless implementation contract that proxies delegate to" reads awkwardly. Consider "a stateless implementation contract that EIP-1167 proxies delegate to" or just "a stateless implementation contract".

• references/protocol/components/depository.mdx:70 — The Zellic audit date says "November 2025" here, but @julien51's suggestion had "June 2025". The security.mdx table (line 65) also says "November 2025". Worth confirming the correct date.

• references/protocol/security.mdx:64 — The Certora report links to /references/protocol/depository/relay-escrow-report-certora.pdf. The old depository/ directory's .mdx files were deleted in this PR — worth confirming the static PDF asset is still served at this path.

---

Summary

The PR is in great shape. The only outstanding item from reviewer feedback is the intent address guidance in for-apps.mdx that @julien51 specifically called out as important. Everything else has been addressed and the documentation quality is excellent throughout.

[github-actions]

Claude finished @ptrwtts's task in 1m 36s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Verify previously flagged items against current state
• Check for any new issues
• Post final review

---

Excellent progress — nearly all review feedback from @julien51, @clemsos, and @ptrwtts has been applied. The documentation quality, structure, and Mermaid diagrams are in great shape.

Previously Flagged Items — All Fixed

• Duplicate text blocks in depository/oracle/hub ✅
• ERC20View added to relay-chain.mdx ✅
• DepositAddressFactory / DepositAddress naming ✅
• Single sweep call in deposit-addresses.mdx ✅
• Security Council table — Update Allocator and Add/Remove Oracle rows ✅
• Security Council "cannot:" wording and trailing sentence removed ✅
• Sui Payload Builder removed from allocator.mdx ✅
• Zellic added to depository.mdx audit list ✅
• Bitcoin section in depository.mdx ✅
• Security Council as owner in depository.mdx ✅
• Withdrawal note for non-solvers in allocator.mdx ✅
• Bug bounty link → /security/bounties ✅
• Repo names in security.mdx corrected ✅
• Oracle two-part overview rewrite ✅
• Hub "finalized funds" wording ✅
• Hub order addresses Info block ✅
• H1 → H2 in evm-depository.mdx and solana-depository.mdx ✅
• refunds.mdx deleted ✅
• Certora PDF still accessible at existing path ✅

---

One Outstanding Item

references/protocol/guides/for-apps.mdx:52-58 — @julien51 flagged twice (and marked as "important") that integrators need guidance on finding the settlement transaction via the intent address. The suggested text was:

To find the settlement transaction for a specific order, derive the intent address on the Relay Chain from the orderId. This deterministic address represents the order on the Hub, and can be looked up on the Relay Chain Explorer to see all related attestation activity (deposit, fill, and settlement).

The current text (lines 52-58) mentions the Explorer and uses orderId as a correlation key, but doesn't explain the intent address concept or how to derive/look it up. Lines 60-80 describe the order address derivation (from chainId, depositor, timestamp, depositId), which is a different concept.

Fix this →

---

Minor Nits (can be follow-up)

• references/protocol/how-it-works.mdx:2 — @ptrwtts agreed the filename should be renamed to match the "Architecture" title (with a redirect). Still how-it-works.mdx with title "Architecture". Fine as a follow-up.

• references/protocol/components/depository.mdx:70 — Zellic date says "November 2025" (matching security.mdx:65), but @julien51's suggestion had "June 2025". Worth confirming which date is correct.

---

Summary

The PR is in great shape — all critical and nearly all outstanding review items have been addressed. The only remaining item that @julien51 specifically called out as important is the intent address lookup guidance in for-apps.mdx. Everything else is ready.

[github-actions]

Claude finished @julien51's task in 1m 57s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Verify previously flagged issues are resolved
• Review documentation structure and navigation
• Review all component and guide pages for quality
• Check style compliance with CLAUDE.md
• Post final review

---

The PR is in excellent shape. All critical issues from previous reviews have been resolved. Here's the full status:

All Previously Flagged Issues — Resolved

• Duplicate text blocks in depository/oracle/hub ✅
• ERC20View added to relay-chain.mdx (line 49) ✅
• DepositAddressFactory / DepositAddress naming corrected throughout ✅
• Single sweep call description in deposit-addresses.mdx (line 64) ✅
• Security Council table — Update Allocator and Add/Remove Oracle rows added (lines 19-20) ✅
• Security Council "cannot:" wording fixed (line 32), trailing sentence removed ✅
• Sui Payload Builder removed from allocator.mdx ✅
• Zellic added to depository.mdx audit list (line 70) ✅
• Bitcoin section added to depository.mdx (lines 44-46) ✅
• Security Council as owner noted in depository.mdx (line 69) ✅
• Withdrawal note for non-solvers in allocator.mdx (lines 40-42) ✅
• Bug bounty link → /security/bounties (line 69) ✅
• Repo names in security.mdx corrected (lines 75-76) ✅
• Oracle two-part overview rewrite (lines 9-14) ✅
• Hub "finalized funds" wording (line 21) ✅
• Hub order addresses Info block (lines 66-68) ✅
• H1 → H2 in evm-depository.mdx and solana-depository.mdx ✅
• refunds.mdx deleted ✅
• Allocator on Aurora correctly noted in relay-chain.mdx (line 51) ✅
• Intent address / settlement tracing guidance in for-apps.mdx (lines 52-58) ✅

Remaining Minor Items

These are non-blocking observations:

references/protocol/how-it-works.mdx:2 — Filename is how-it-works.mdx but title is "Architecture". @ptrwtts agreed to rename or add a redirect. Fine as a follow-up.

references/protocol/security.mdx:64 — Certora report links to /references/protocol/depository/relay-escrow-report-certora.pdf. The depository/ directory's .mdx files were deleted in this PR, but the PDF is a static asset that should still be served. Worth a quick manual check after deploy.

references/protocol/components/deposit-addresses.mdx:72 — The text still says "The sweeper is a stateless implementation contract" — but the heading was correctly renamed to ### DepositAddress. Consider updating this sentence to say "The DepositAddress is a stateless implementation contract" for consistency.

Fix this →

references/protocol/components/deposit-addresses.mdx:89 — Similar leftover: "Both the factory and sweeper are immutable contracts" → "Both the factory and DepositAddress are immutable contracts"

Fix this →

---

Summary

The PR is ready to merge. All critical issues, duplicate text blocks, and agreed-upon reviewer suggestions have been applied. The documentation quality, narrative structure, Mermaid diagrams, and cross-linking are excellent throughout. The only remaining items are two minor "sweeper" → "DepositAddress" terminology leftovers in deposit-addresses.mdx and two low-priority follow-ups (filename rename, PDF path check) that can be addressed post-merge.

[github-actions]

Claude finished @julien51's task in 1m 34s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Verify previously flagged items against current state
• Check for any new issues
• Post final review

---

All critical issues and agreed-upon reviewer feedback from previous rounds have been addressed. The documentation quality, narrative structure, Mermaid diagrams, and cross-linking are excellent throughout. Here's the full verification:

All Previously Flagged Items — Resolved

• Duplicate text blocks in depository/oracle/hub ✅
• ERC20View added to relay-chain.mdx (line 49) ✅
• DepositAddressFactory / DepositAddress naming corrected (lines 11, 59, 70) ✅
• Single sweep call description (line 64) ✅
• Security Council table — Update Allocator and Add/Remove Oracle rows (lines 19-20) ✅
• Security Council "cannot:" wording (line 32) and trailing sentence removed ✅
• Sui Payload Builder removed from allocator.mdx ✅
• Zellic added to depository.mdx audit list (line 70) ✅
• Bitcoin section added to depository.mdx (lines 44-46) ✅
• Security Council as owner noted in depository.mdx (line 69) ✅
• Withdrawal note for non-solvers in allocator.mdx (lines 40-42) ✅
• Bug bounty link → /security/bounties (security.mdx line 69) ✅
• Repo names in security.mdx corrected (lines 75-76) ✅
• Oracle two-part overview (lines 9-14) ✅
• Hub "finalized funds" wording (line 21) ✅
• Hub order addresses Info block (lines 66-68) ✅
• H1 → H2 in evm-depository.mdx and solana-depository.mdx ✅
• refunds.mdx deleted ✅
• Allocator on Aurora correctly noted in relay-chain.mdx (line 51) ✅
• Intent address / settlement tracing guidance added to for-apps.mdx ✅

---

Remaining Minor Items (non-blocking)

references/protocol/components/deposit-addresses.mdx:72 — The text still says "The sweeper is a stateless implementation contract" but the heading was correctly renamed to ### DepositAddress. Should say "The DepositAddress is a stateless implementation contract" for consistency. Same on line 89: "Both the factory and sweeper are immutable contracts" → "Both the factory and DepositAddress are immutable contracts".

Fix terminology →

references/protocol/components/deposit-addresses.mdx:11 — Minor grammar: "a stateless implementation contract that proxies delegate to" reads a bit awkwardly. Consider "a stateless implementation contract that EIP-1167 proxies delegate to" or "a stateless implementation contract to which proxies delegate".

references/protocol/how-it-works.mdx:2 — Filename is how-it-works.mdx but title is "Architecture". @ptrwtts agreed to rename or add a redirect. Fine as a follow-up.

references/protocol/components/depository.mdx:70 — Zellic date says "November 2025" (matching security.mdx:65), but @julien51's suggestion had "June 2025". Worth confirming which date is correct.

references/protocol/security.mdx:64 — Certora report links to /references/protocol/depository/relay-escrow-report-certora.pdf. The depository/ directory's .mdx files were deleted in this PR — worth a quick check that the static PDF asset still resolves after deploy.

---

Summary

The PR is ready to merge. All critical issues, duplicate text blocks, and agreed-upon reviewer suggestions have been applied. The writing quality and structure are excellent. The only remaining items are two minor "sweeper" → "DepositAddress" terminology leftovers in deposit-addresses.mdx and a few low-priority follow-ups (filename rename, audit date confirmation, PDF path check) that can be addressed post-merge.

[github-actions]

Claude encountered an error —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Review documentation structure and navigation
• Review component pages and guides
• Check outstanding review feedback
• Post final review

[github-actions]

Claude finished @julien51's task in 2m 25s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Verify previously flagged items against current state
• Check for new issues (style, accuracy, links)
• Post final review

---

The PR is in excellent shape — all critical items and nearly all reviewer suggestions from previous rounds have been applied. The narrative-driven structure, Mermaid diagrams, and flow walkthroughs are a significant improvement. @julien51's final review dismissed with "ok I think this looks good!"

All Previously Flagged Items — Resolved

• Duplicate text blocks in depository/oracle/hub ✅
• ERC20View added to relay-chain.mdx ✅
• DepositAddressFactory / DepositAddress naming in headings ✅
• Single sweep call description ✅
• Security Council table expanded (Update Allocator, Add/Remove Oracle) ✅
• Security Council "cannot:" wording and trailing sentence ✅
• Zellic added to depository.mdx and security.mdx ✅
• Bitcoin section in depository.mdx ✅
• Security Council as owner in depository.mdx ✅
• Withdrawal note for non-solvers in allocator.mdx ✅
• Bug bounty link → /security/bounties ✅
• Repo names in security.mdx corrected ✅
• Oracle two-part overview ✅
• Hub "finalized funds" wording ✅
• Hub order addresses Info block ✅
• H1 → H2 in evm-depository.mdx ✅
• refunds.mdx deleted ✅
• Intent address / settlement tracing in for-apps.mdx ✅

---

Remaining Items

references/protocol/components/deposit-addresses.mdx — "sweeper" terminology leftovers. The heading was correctly renamed to ### DepositAddress, but the body text still uses "sweeper" in 3 places:

• Line 72: "The sweeper is a stateless implementation contract" → "The DepositAddress is a stateless implementation contract"
• Line 78: "The sweeper includes a receive() function" → "The DepositAddress includes a receive() function"
• Line 89: "Both the factory and sweeper are immutable contracts" → "Both the factory and DepositAddress are immutable contracts"

Fix terminology →

references/protocol/contracts/solana-depository.mdx:13 — H1 header in body content. # Module relay_depository should be `## Module `relay_depository. Per CLAUDE.md: "No H1 in body content (frontmatter title serves as H1)". (This appears to be auto-generated from Anchor IDL, so likely needs a template fix.)

Fix H1 →

references/protocol/components/allocator.mdx:97 — Sui still mentioned in the MPC signing section: "enabling support for EVM, Solana, Bitcoin, Sui, and other VMs". Previous reviews flagged removing the Sui Payload Builder row (done ✅), but this separate mention in the chain-agnostic bullet remains. @ptrwtts said to remove Sui for now given limited support — this reference may warrant the same treatment.

---

Minor Nits (non-blocking)

• references/protocol/how-it-works.mdx:2 — Filename is how-it-works.mdx but title is "Architecture". @ptrwtts agreed to rename with a redirect — fine as a follow-up.
• references/protocol/security.mdx:77 — Display label says relay-oracle but links to relay-protocol-oracle. Minor cosmetic inconsistency.
• references/protocol/components/depository.mdx:70 — Zellic date says "November 2025". @julien51's original suggestion had "June 2025". Both security.mdx and depository.mdx are consistent with each other (both say November 2025), so just worth confirming the correct date.

---

Summary

The PR is ready to merge with only minor cleanup remaining — 3 "sweeper" → "DepositAddress" text replacements in deposit-addresses.mdx, one H1→H2 fix in the auto-generated Solana reference, and an optional Sui mention removal in allocator.mdx. All critical issues and agreed-upon reviewer suggestions have been addressed. The documentation quality, structure, and cross-linking are excellent throughout.

[github-actions]

Claude finished @julien51's task in 1m 39s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Review remaining outstanding items from previous reviews
• Check for new issues (style, accuracy, consistency)
• Post final review

---

The PR is in excellent shape. All critical issues and nearly all reviewer suggestions have been addressed. Here's the full status:

All Previously Flagged Items — Resolved

• Duplicate text blocks in depository/oracle/hub ✅
• ERC20View added to relay-chain.mdx (line 49) ✅
• DepositAddressFactory / DepositAddress naming in headings (lines 59, 70) ✅
• Single sweep call description (line 64) ✅
• Security Council table expanded with Update Allocator and Add/Remove Oracle rows ✅
• Security Council "cannot:" wording (line 34) and trailing sentence removed ✅
• Sui Payload Builder removed from allocator.mdx ✅
• Zellic added to depository.mdx audit list (line 70) ✅
• Bitcoin section in depository.mdx (lines 44-46) ✅
• Security Council as owner in depository.mdx (line 69) ✅
• Withdrawal note for non-solvers in allocator.mdx (lines 43-45) ✅
• Bug bounty link → /security/bounties (line 70) ✅
• Repo names in security.mdx corrected (lines 76-77) ✅
• Oracle two-part overview (lines 9-14) ✅
• Hub "finalized funds" wording (line 21) ✅
• Hub order addresses Info block (lines 66-68) ✅
• H1 → H2 in evm-depository.mdx (line 7) ✅
• H1 → H2 in solana-depository.mdx (line 7) ✅
• refunds.mdx deleted ✅
• Allocator correctly noted as Aurora in relay-chain.mdx (line 51) ✅
• Intent address / settlement tracing guidance in for-apps.mdx ✅
• Certora PDF still accessible at existing path ✅

---

Remaining Items

references/protocol/components/deposit-addresses.mdx — "sweeper" terminology leftovers. The headings were correctly renamed to DepositAddressFactory and DepositAddress, but the body text still uses "sweeper" in 3 places:

• Line 72: "The sweeper is a stateless implementation contract" → "The DepositAddress is a stateless implementation contract"
• Line 78: "The sweeper includes a receive() function" → "The DepositAddress includes a receive() function"
• Line 89: "Both the factory and sweeper are immutable contracts" → "Both the factory and DepositAddress are immutable contracts"

Fix terminology →

references/protocol/contracts/solana-depository.mdx:13 — H1 header in body content. # Module relay_depository should be `## Module `relay_depository. Per CLAUDE.md: "No H1 in body content (frontmatter title serves as H1)". (Likely auto-generated from Anchor IDL — may need a template fix.)

Fix H1 →

references/protocol/components/allocator.mdx:97 — Sui still mentioned in the MPC signing section: "enabling support for EVM, Solana, Bitcoin, Sui, and other VMs". The Sui Payload Builder row was correctly removed, but this text reference remains. Given @ptrwtts said to remove Sui for now, consider removing it here too.

references/protocol/security.mdx:77 — Minor display inconsistency. The display label says relay-oracle but the link points to relay-protocol-oracle. Consider using the actual repo name as the label for clarity: [`relay-protocol-oracle`](https://github.com/relayprotocol/relay-protocol-oracle)

---

Minor Nits (non-blocking)

• references/protocol/how-it-works.mdx:2 — Filename is how-it-works.mdx but title is "Architecture". @ptrwtts agreed to rename with a redirect. Fine as a follow-up.

• references/protocol/components/deposit-addresses.mdx:11 — Minor grammar: "a stateless implementation contract that proxies delegate to" reads a bit awkwardly. Consider "a stateless implementation contract to which proxies delegate".

• references/protocol/components/depository.mdx:70 — Zellic date says "November 2025" (matching security.mdx:66). @julien51's original suggestion had "June 2025". Both files are consistent with each other, but worth confirming the correct date.

---

Summary

The PR is ready to merge with only minor cleanup remaining — 3 "sweeper" → "DepositAddress" text replacements in deposit-addresses.mdx, one more H1→H2 fix in the auto-generated Solana reference, and an optional Sui text mention removal in allocator.mdx. All critical issues and agreed-upon reviewer suggestions have been addressed. The documentation quality, narrative structure, Mermaid diagrams, and cross-linking are excellent throughout.

[github-actions]

Claude finished @julien51's task in 1m 41s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Review remaining issues from previous review rounds
• Check for any new issues
• Post final review

---

The PR is in excellent shape. All critical issues from previous review rounds have been addressed. The narrative-driven structure, Mermaid diagrams, and flow walkthroughs are a major improvement. Here's the full status:

All Previously Flagged Items — Resolved

• Duplicate text blocks in depository/oracle/hub ✅
• ERC20View added to relay-chain.mdx (line 49) ✅
• DepositAddressFactory / DepositAddress naming in headings (lines 59, 70) ✅
• Single sweep call description (line 64) ✅
• Security Council table expanded with Update Allocator and Add/Remove Oracle rows (lines 19-20) ✅
• Security Council "cannot:" wording (line 34) and trailing sentence removed ✅
• Sui Payload Builder removed from allocator.mdx table ✅
• Zellic added to depository.mdx audit list (line 70) ✅
• Bitcoin section in depository.mdx (lines 44-46) ✅
• Security Council as owner in depository.mdx (line 69) ✅
• Withdrawal note for non-solvers in allocator.mdx (lines 43-45) ✅
• Bug bounty link → /security/bounties (line 70) ✅
• Repo names in security.mdx corrected (lines 76-77) ✅
• Oracle two-part overview (lines 9-14) ✅
• Hub "finalized funds" wording (line 21) ✅
• Hub order addresses Info block (lines 66-68) ✅
• H1 → H2 in evm-depository.mdx (line 7) and solana-depository.mdx (line 7) ✅
• refunds.mdx deleted ✅
• Allocator correctly noted as Aurora in relay-chain.mdx (line 51) ✅
• Intent address / settlement tracing guidance in for-apps.mdx (lines 52-58) ✅

---

Remaining Items

references/protocol/components/deposit-addresses.mdx — "sweeper" terminology leftovers. The headings were correctly renamed, but the body text still uses "sweeper" in 3 places:

• Line 72: "The sweeper is a stateless implementation contract" → "The DepositAddress is a stateless implementation contract"
• Line 78: "The sweeper includes a receive() function" → "The DepositAddress includes a receive() function"
• Line 89: "Both the factory and sweeper are immutable contracts" → "Both the factory and DepositAddress are immutable contracts"

Fix terminology →

references/protocol/contracts/solana-depository.mdx:13 — H1 header in body content. # Module relay_depository should be `## Module `relay_depository. Per CLAUDE.md: "No H1 in body content (frontmatter title serves as H1)". (Likely auto-generated from Anchor IDL.)

Fix H1 →

references/protocol/components/allocator.mdx:97 — Sui still mentioned in the MPC signing section: "enabling support for EVM, Solana, Bitcoin, Sui, and other VMs". The Sui Payload Builder row was correctly removed from the table, but this text reference remains. Given @ptrwtts said to remove Sui for now, consider removing it here too.

Remove Sui mention →

references/protocol/security.mdx:77 — Minor display inconsistency. The display label says relay-oracle but the link points to relay-protocol-oracle. Consider using the actual repo name: [`relay-protocol-oracle`](https://github.com/relayprotocol/relay-protocol-oracle)

---

Minor Nits (non-blocking)

• references/protocol/how-it-works.mdx:2 — Filename is how-it-works.mdx but title is "Architecture". @ptrwtts agreed to rename with a redirect. Fine as a follow-up.

• references/protocol/components/deposit-addresses.mdx:11 — Minor grammar: "a stateless implementation contract that proxies delegate to" reads a bit awkwardly. Consider "a stateless implementation contract to which proxies delegate".

• references/protocol/components/depository.mdx:70 — Zellic date says "November 2025" (matching security.mdx:66). @julien51's original suggestion had "June 2025". Both files are consistent with each other, but worth confirming the correct date.

---

Summary

The PR is ready to merge with only minor cleanup remaining — 3 "sweeper" → "DepositAddress" text replacements in deposit-addresses.mdx, one more H1→H2 fix in the Solana reference, a Sui text mention in allocator.mdx, and a repo display name fix in security.mdx. All critical issues and agreed-upon reviewer suggestions have been addressed. The documentation quality, narrative structure, Mermaid diagrams, and cross-linking are excellent throughout.

[github-actions]

Claude finished @julien51's task in 1m 20s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Check remaining items from previous review rounds
• Review for any new issues
• Post final review

---

The PR is in excellent shape — all critical issues and nearly all agreed-upon reviewer suggestions have been applied across 8 review rounds. The narrative-driven structure, Mermaid diagrams, and flow walkthroughs are a major improvement. @julien51 dismissed with "ok I think this looks good!"

All Previously Flagged Items — Resolved

Duplicate text blocks ✅ | ERC20View in relay-chain.mdx ✅ | DepositAddressFactory/DepositAddress heading renames ✅ | Single sweep call ✅ | Security Council table expanded ✅ | Security Council "cannot:" wording ✅ | Trailing sentence removed ✅ | Sui Payload Builder removed from table ✅ | Zellic added to depository.mdx ✅ | Bitcoin section ✅ | Security Council as owner ✅ | Withdrawal note for non-solvers ✅ | Bug bounty link → /security/bounties ✅ | Repo names in security.mdx ✅ | Oracle two-part overview ✅ | Hub "finalized funds" wording ✅ | Hub order addresses Info block ✅ | H1→H2 in evm-depository.mdx ✅ | H1→H2 in solana-depository.mdx (line 7) ✅ | refunds.mdx deleted ✅ | Allocator noted as Aurora ✅ | Intent address guidance in for-apps.mdx ✅

---

Remaining Items

references/protocol/components/deposit-addresses.mdx — "sweeper" terminology leftovers. Headings were correctly renamed, but body text still uses "sweeper" in 3 places:

• Line 72: "The sweeper is a stateless implementation contract" → "The DepositAddress is a stateless implementation contract"
• Line 78: "The sweeper includes a receive() function" → "The DepositAddress includes a receive() function"
• Line 89: "Both the factory and sweeper are immutable contracts" → "Both the factory and DepositAddress are immutable contracts"

Fix terminology →

references/protocol/contracts/solana-depository.mdx:13 — H1 in body content. # Module relay_depository should be `## Module `relay_depository. Per CLAUDE.md: "No H1 in body content." (Likely auto-generated from Anchor IDL.)

Fix H1 →

references/protocol/components/allocator.mdx:97 — Sui still mentioned in the MPC signing section: "enabling support for EVM, Solana, Bitcoin, Sui, and other VMs". The Sui Payload Builder row was correctly removed from the table, but this text reference remains. Given @ptrwtts said to remove Sui for now, consider removing it here too.

Remove Sui mention →

references/protocol/security.mdx:77 — Minor display inconsistency. Display label says relay-oracle but the link points to relay-protocol-oracle. Consider using the actual repo name: [`relay-protocol-oracle`](https://github.com/relayprotocol/relay-protocol-oracle)

---

Minor Nits (non-blocking)

• references/protocol/how-it-works.mdx:2 — Filename is how-it-works.mdx but title is "Architecture". @ptrwtts agreed to rename with a redirect. Fine as a follow-up.

• references/protocol/components/deposit-addresses.mdx:11 — Minor grammar: "a stateless implementation contract that proxies delegate to" reads awkwardly. Consider "a stateless implementation contract to which proxies delegate".

• references/protocol/components/depository.mdx:70 — Zellic date says "November 2025" (matching security.mdx:66). @julien51's original suggestion had "June 2025". Both files are consistent with each other, so just confirm the correct date.

---

Summary

The PR is ready to merge with only minor cleanup remaining — 3 "sweeper" → "DepositAddress" text replacements in deposit-addresses.mdx, one H1→H2 fix in the Solana reference, a Sui text mention in allocator.mdx, and a display name fix in security.mdx. All critical issues and agreed-upon reviewer suggestions have been addressed. The documentation quality, narrative structure, Mermaid diagrams, and cross-linking are excellent throughout.

[github-actions]

Claude encountered an error —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Check remaining issues from previous review rounds
• Review for any new issues
• Post final review

---

The PR is in excellent shape. All critical issues and nearly all agreed-upon reviewer suggestions from previous rounds have been addressed. Here's the full verification:

All Previously Flagged Items — Resolved

• Duplicate text blocks in depository/oracle/hub ✅
• ERC20View added to relay-chain.mdx (line 49) ✅
• DepositAddressFactory / DepositAddress naming in headings and body (lines 11, 59, 70, 72, 78, 89) ✅
• Single sweep call description (line 64) ✅
• Security Council table — Update Allocator and Add/Remove Oracle rows (lines 19-20) ✅
• Security Council "cannot:" wording (line 34) and trailing sentence removed ✅
• Sui Payload Builder removed from allocator.mdx table ✅
• Zellic added to depository.mdx audit list (line 70) ✅
• Bitcoin section in depository.mdx (lines 44-46) ✅
• Security Council as owner in depository.mdx (line 69) ✅
• Withdrawal note for non-solvers in allocator.mdx (lines 43-45) ✅
• Bug bounty link → /security/bounties (line 70) ✅
• Repo names in security.mdx corrected (lines 76-77) ✅
• Oracle two-part overview (lines 9-14) ✅
• Hub "finalized funds" wording (line 21) ✅
• Hub order addresses Info block (lines 66-68) ✅
• H1 → H2 in evm-depository.mdx and solana-depository.mdx ✅
• refunds.mdx deleted ✅
• Allocator on Aurora correctly noted in relay-chain.mdx (line 51) ✅
• Intent address / settlement tracing guidance in for-apps.mdx (lines 52-58) ✅
• "sweeper" → "DepositAddress" terminology in deposit-addresses.mdx (lines 72, 78, 89) ✅

Remaining Minor Items (non-blocking)

references/protocol/components/allocator.mdx:97 — Sui is still mentioned in the MPC signing section: "enabling support for EVM, Solana, Bitcoin, Sui, and other VMs". The Sui Payload Builder row was correctly removed from the table, but this prose mention remains. Given @ptrwtts said to remove Sui for now, consider removing it here too.

Fix this →

references/protocol/how-it-works.mdx:2 — Filename is how-it-works.mdx but title is "Architecture". @ptrwtts agreed to rename with a redirect. Fine as a follow-up.

references/protocol/components/depository.mdx:70 — Zellic date says "November 2025" (matching security.mdx:66). @julien51's original suggestion had "June 2025". Both files are consistent with each other, so just worth confirming the correct date.

---

Summary

The PR is ready to merge. All critical issues, duplicate text blocks, and agreed-upon reviewer suggestions have been applied. The documentation quality, narrative structure, Mermaid diagrams, and cross-linking are excellent throughout. The only remaining items are a single Sui text mention in allocator.mdx and two low-priority follow-ups (filename rename, audit date confirmation) that can be addressed post-merge.

[github-actions]

Claude finished @julien51's task in 1m 20s —— View job

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Review remaining flagged items from previous reviews
• Review documentation structure and navigation
• Check style compliance with CLAUDE.md
• Post final review

---

Excellent work on this rewrite. The narrative-driven structure, Mermaid sequence diagrams, and component-focused pages are a massive improvement. I've read through all 27 changed files and verified the current state against all previous review rounds.

All Previously Flagged Items — Resolved

Every critical and agreed-upon reviewer suggestion from the 10+ previous review rounds has been applied:

Duplicate text blocks ✅ | ERC20View in relay-chain.mdx ✅ | DepositAddressFactory/DepositAddress naming ✅ | Single sweep call ✅ | Security Council table expanded ✅ | "cannot:" wording ✅ | Trailing sentence removed ✅ | Sui Payload Builder removed from table ✅ | Zellic in depository.mdx ✅ | Bitcoin section ✅ | Security Council as owner ✅ | Withdrawal note for non-solvers ✅ | Bug bounty link → /security/bounties ✅ | Repo names in security.mdx ✅ | Oracle two-part overview ✅ | Hub "finalized funds" ✅ | Order addresses Info block ✅ | H1→H2 in evm-depository.mdx and solana-depository.mdx ✅ | refunds.mdx deleted ✅ | Allocator noted as Aurora ✅ | Intent address guidance in for-apps.mdx ✅ | "sweeper"→"DepositAddress" terminology ✅ | how-it-works.mdx title matches filename ✅

---

Remaining Items

references/protocol/components/allocator.mdx:97 — Sui still mentioned in prose. The Sui Payload Builder row was correctly removed from the table, but line 97 still reads: "enabling support for EVM, Solana, Bitcoin, Sui, and other VMs". Given @ptrwtts said to remove Sui for now, this text reference should match.

Fix this →

references/protocol/security.mdx:77 — Display name mismatch. The display label says relay-protocol-oracle but the text before the link says relay-oracle implicitly via the old review context. Actually on re-read, line 77 shows [`relay-protocol-oracle`](https://github.com/relayprotocol/relay-protocol-oracle) which is correct. ✅

references/protocol/components/depository.mdx:70 — Zellic audit date ambiguity. Line 70 says Zellic audited in "November 2025", matching security.mdx:66. But @julien51's original suggestion had "June 2025". Both files are consistent with each other, so just worth confirming the correct date with the team.

---

Summary

The PR is in great shape — all critical issues and agreed-upon reviewer feedback have been addressed. The only actionable item remaining is the single Sui text mention in allocator.mdx:97. The Zellic audit date is a question for the team rather than a code issue. Documentation quality, structure, cross-linking, and Mermaid diagrams are excellent throughout.