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 encountered an error —— View job

---

I'll analyze this and get back to you.

[github-actions]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[github-actions]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[github-actions]

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

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Check previous review items against current state
• Review for any new issues
• Post final review

---

Great progress since the last review — the duplicate text blocks in depository.mdx, oracle.mdx, and hub.mdx are all fixed, refunds.mdx has been deleted, the bug bounty link now points to /security/bounties, the repo names in security.mdx are corrected, the Allocator is properly noted as being on Aurora (not Relay Chain), and the order addresses Info block has been added to hub.mdx. The majority of the critical and outstanding items from the previous review have been addressed.

Here's what remains:

---

Outstanding Review Feedback Still Not Applied

references/protocol/components/relay-chain.mdx:47-48 — ERC20View is still missing. Both @julien51 and @ptrwtts agreed to remove the Allocator bullet (done ✅) and add ERC20View. The current list only has Hub and Oracle. Should be:

- **[Hub](/references/protocol/components/hub)** — The ERC6909 multi-token ledger that tracks all balances
- **[Oracle](/references/protocol/components/oracle)** — The contract that processes oracle attestations (mint, burn, transfer)
- **ERC20View** — A wrapper contract that exposes Hub token balances as standard ERC20 tokens for wallet compatibility

Fix this →

references/protocol/components/deposit-addresses.mdx — Contract naming corrections from @julien51 not applied:

• Line 11: Still says DepositFactory and DepositSweeper → should be DepositAddressFactory and DepositAddress
• Line 59: Section heading still says ### DepositFactory → should be ### DepositAddressFactory
• Line 71: Section heading still says ### DepositSweeper → should be ### DepositAddress
• Lines 63-65: Still shows separate deployAndSweep and sweep functions. Per @julien51, there is now a single sweep call that deploys if needed.

Fix naming →

references/protocol/components/security-council.mdx:15-20 — @julien51's suggestion to add "Update Allocator" and "Add/Remove Oracle instances" rows to the table was not applied. Current table only has Pause, Unpause, Replace Allocator, and Change Membership.

Fix table →

references/protocol/components/security-council.mdx:30 — @julien51 suggested changing "governs the Allocator only. It cannot:" to just "The Security Council cannot:" — current text on line 30 still reads "The Security Council governs the Allocator only. It cannot:"

references/protocol/components/security-council.mdx:37 — @julien51 suggested removing the trailing content ("Its authority is limited to controlling the flow of withdrawals — pausing them in emergencies and replacing the Allocator if necessary."). This line is still present.

references/protocol/components/allocator.mdx:61 — Sui Payload Builder is still listed in the table. @ptrwtts said to remove Sui for now given limited support.

Remove Sui →

references/protocol/components/depository.mdx:70 — @julien51 suggested adding Zellic to the audit list. Currently reads: "Reviewed by Spearbit (February 2025) and Certora (June 2025)". Should include "and Zellic (June 2025)" per julien51's latest suggestion.

Fix audit list →

references/protocol/guides/for-apps.mdx:52 — @julien51 flagged (and re-confirmed as "important") that this section should show how an integrator can find the settlement transaction via the intent address. The current text has been expanded with order address derivation details (lines 60-80), but the specific guidance about looking up the intent address on the Relay Chain Explorer that @julien51 requested is not present.

references/protocol/how-it-works.mdx:174 — Still says "the user needs to be refunded" — this is actually correct now (earlier review noted "refilled" which has been fixed ✅).

---

Style Issues (per CLAUDE.md)

H1 headers in body content — Per docs standards, "No H1 in body content (frontmatter title serves as H1)":

• references/protocol/contracts/evm-depository.mdx:7 — # Solidity API should be ## Solidity API
• references/protocol/contracts/solana-depository.mdx:7 — # API should be ## API

Fix H1 headers →

---

Summary

Most critical issues from the previous review are resolved (duplicate text blocks fixed, refunds.mdx deleted, security.mdx repo names and bounty link corrected, Allocator location clarified). The remaining items are agreed-upon reviewer suggestions that haven't been applied yet — primarily the deposit-addresses contract renaming, security-council table expansion, ERC20View on relay-chain, Sui removal from allocator, Zellic audit addition to depository, and H1→H2 fixes in contract reference pages.

[github-actions]

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

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Check previous review items against current state
• Review for any new issues
• Post final review

---

Good progress since the last review — several important items have been addressed:

Fixed since last review: duplicate text blocks in depository/oracle/hub ✅, refunds.mdx deleted ✅, bug bounty link → /security/bounties ✅, repo names in security.mdx corrected ✅, Zellic audit added to security.mdx table ✅, Allocator noted as Aurora not Relay Chain ✅, Oracle two-part overview rewrite ✅, "finalized funds" wording in hub.mdx ✅, order addresses Info block in hub.mdx ✅, Bitcoin section in depository.mdx ✅, Security Council as owner in depository.mdx ✅, withdrawal note for non-solvers in allocator.mdx ✅

---

Outstanding Review Feedback Still Not Applied

These are all items that reviewers agreed on but haven't made it into the code yet:

references/protocol/components/relay-chain.mdx:47-48 — ERC20View still missing. Both @julien51 and @ptrwtts agreed to add it. Current list only has Hub and Oracle. Should add:

- **ERC20View** — A wrapper contract that exposes Hub token balances as standard ERC20 tokens for wallet compatibility

Fix this →

references/protocol/components/deposit-addresses.mdx — Contract naming corrections from @julien51 not applied:

• Line 11: Still says DepositFactory and DepositSweeper → should be DepositAddressFactory and DepositAddress
• Line 59: Heading still says ### DepositFactory → should be ### DepositAddressFactory
• Line 70: Heading still says ### DepositSweeper → should be ### DepositAddress
• Lines 63-64: Still shows separate computeDepositAddress and sweep as "re-sweep" only. Per @julien51, there is now a single sweep call that deploys if needed — no separate deployAndSweep.

Fix naming →

references/protocol/components/security-council.mdx — Three suggestions from @julien51 not applied:

1. Lines 15-20: Table missing "Update Allocator" and "Add/Remove Oracle instances" rows
2. Line 30: Still says "The Security Council governs the Allocator only. It cannot:" → should be just "The Security Council cannot:"
3. Line 37: Trailing sentence "Its authority is limited to controlling the flow of withdrawals — pausing them in emergencies and replacing the Allocator if necessary." should be removed

Fix security-council →

references/protocol/components/allocator.mdx:70 — Sui Payload Builder still listed in the table. @ptrwtts said to remove Sui for now given limited support.

Remove Sui →

references/protocol/components/depository.mdx:70 — Zellic missing from audit list. @julien51 explicitly suggested adding Zellic. Currently reads:

Reviewed by Spearbit (February 2025) and Certora (June 2025)

Should be:

Reviewed by Spearbit (February 2025), Certora (June 2025) and Zellic (June 2025)

Fix audit list →

references/protocol/guides/for-apps.mdx:52 — @julien51 flagged (and re-confirmed as "important") that integrators need guidance on finding the settlement transaction via the intent address. The current text (lines 52-80) has good order address derivation details, but the specific guidance about looking up the intent address on the Relay Chain Explorer that @julien51 requested is not present.

Add intent address guidance →

---

Style Issues (per CLAUDE.md)

H1 headers in body content — Per docs standards, "No H1 in body content (frontmatter title serves as H1)":

• references/protocol/contracts/evm-depository.mdx:7 — # Solidity API should be ## Solidity API
• references/protocol/contracts/solana-depository.mdx:7 — # API should be ## API

Fix H1 headers →

---

Summary

Most critical items from earlier reviews are resolved. The remaining items are all agreed-upon reviewer suggestions that haven't been applied yet — 7 items across 7 files. The deposit-addresses contract renaming and security-council table expansion are the largest changes; the rest are single-line fixes.

[github-actions]

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

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Check previous review items against current state
• Review for any new issues
• Post final review

---

Excellent progress — the vast majority of review feedback has now been applied. Here's the current status:

Previously Outstanding Items — Now Fixed

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

Remaining Items

references/protocol/guides/for-apps.mdx:52-80 — @julien51 flagged twice (and marked as "important") that integrators need guidance on finding the settlement transaction via the intent address on the Relay Chain Explorer. The current text (lines 52-80) has good order address derivation details, but the specific intent address lookup guidance that @julien51 requested is still not present. Lines 52-53 mention the Explorer but don't explain how to use the intent address to find a specific order's activity.

Add intent address guidance →

references/protocol/security.mdx:64 — The Certora report links to /references/protocol/depository/relay-escrow-report-certora.pdf. The PDF still exists at that path, but the old depository/ directory's .mdx files were deleted in this PR. Worth confirming this static asset path continues to work in the built site.

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 added. The file is still how-it-works.mdx with title "Architecture". This is a minor consistency issue that could be addressed in a follow-up.

---

Summary

Nearly all review feedback has been applied — great work. The one outstanding item that @julien51 specifically called out as important is the intent address lookup guidance in for-apps.mdx. Everything else is in excellent shape and the documentation quality is very high.

[github-actions]

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

---

Code Review: Protocol Documentation Rewrite

• Gather context and read changed files
• Verify previously flagged items are fixed
• Check for any new issues
• Post final review

---

Nearly all feedback from previous reviews has been applied — excellent work. Here's the current status:

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. 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/depository.mdx:70 — The Zellic audit date says "November 2025" here (matching security.mdx:65), but @julien51's suggestion had "June 2025". Worth confirming which date is correct.

---

Summary

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

[julien51]

ok I think this looks good!

[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.