Rewrite protocol docs: add Relay Chain, Allocator, Mermaid diagrams, …#237
Open
Rewrite protocol docs: add Relay Chain, Allocator, Mermaid diagrams, …#237
Conversation
…and legal language fixes 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 - Apply legal language fixes (crosschain, revert, destination, asset terminology) - Add 13 URL redirects for old pages - Delete 8 obsolete files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Visual diagram showing the three chain roles in the protocol (Origin, Relay Chain, Destination) with components, actors, and cost annotations. Uses inline HTML/CSS for full visual control with brand purple styling, dark mode support, and responsive mobile layout. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Move Relay Chain into Components group, add Security Council and MPC Signing pages - Consolidate MPC content back into Allocator page - Create Contracts sidebar group (Addresses, EVM/SVM Depository Reference) - Rewrite Overview with 5 key dimensions (Speed, Cost, Capital Efficiency, Coverage, UX) - Restructure How It Works into Architecture + Flows sections with Mermaid diagrams - Add settlement flow image to Overview - Remove Design page, absorb relevant content into Overview - Update solver guide for direct protocol integration (not API) - Expand Addresses page with Relay Chain and Aurora contract placeholders - Update Security page to link to Security Council component - Clean up cross-references and internal links Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Link to Relay Chain instead of "dedicated low-cost settlement hub" - Remove Info callout, Source Code section, and redundant links from overview - Tighten Failure UX and Coverage copy - Clarify Hub and Allocator both live on Relay Chain in how-it-works Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…awal updates - Oracle reframed as pull-based: never initiates, only responds to requests - Settlement flow: solver requests attestation from Oracle, submits to Hub - Withdrawal flow: solver drives entire flow through Oracle - Add Refund flow: solver-initiated instant refund on origin, settled like a fill - Rename Revert flow to Forced Exit: user-initiated after fill window expires - Add solver abandon concept to shorten forced exit window - Update Oracle component page: request-response pipeline, five attestation types - Change all "revert" terminology to "refund" in user-facing docs - Simplify diagrams: merge Oracle validators/contract, remove NEAR MPC participant Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…eanup - Merge Fast Refund, Slow Refund, and Self Refund flows into the Architecture page - Replace TBD addresses with actual deployed contracts on Relay Chain and Aurora - Link contract addresses to block explorers (explorer.chain.relay.link, explorer.aurora.dev) - Remove bracketed annotations from security page headings Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New protocol component page documenting the DepositFactory and DepositSweeper contracts that power counterfactual deposit addresses via EIP-1167 minimal proxies. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
clemsos
reviewed
Mar 2, 2026
| - **`deposit_token(amount, id)`** — Deposit SPL tokens (including Token-2022) | ||
|
|
||
| Funds are held in a program-derived address (PDA) vault. | ||
|
|
Collaborator
There was a problem hiding this comment.
should we add a mention about btc works here ?
clemsos
reviewed
Mar 2, 2026
| - **Operator system** — Grant an address full control over all token balances | ||
| - **EIP-712 permits** — Gasless approval signatures | ||
|
|
||
| ## Withdrawal Addresses |
Collaborator
There was a problem hiding this comment.
there is also the "order addresses" that works in a similar fashion when a user request an order and the solver filled it. Is it worth mentioning here?
clemsos
reviewed
Mar 2, 2026
|
|
||
| The Oracle is a decentralized validator set that verifies crosschain activity and produces signed attestations for the [Hub](/references/protocol/components/hub) on the [Relay Chain](/references/protocol/components/relay-chain). Validators independently read origin and destination chains, verify that deposits and fills occurred correctly, and sign EIP-712 attestations. Attestations require signatures from a threshold of validators before the Hub will accept them. | ||
|
|
||
| The Oracle never initiates actions — it only responds to requests. Solvers and users call the Oracle when they need verification, and the Oracle returns signed attestations that the caller then submits to the Hub. This **pull-based** model keeps costs low and avoids the overhead of maintaining persistent message channels to every chain. |
Collaborator
There was a problem hiding this comment.
it only "witness" what has already happened onchain ?
clemsos
reviewed
Mar 2, 2026
Comment on lines
+67
to
+73
| ### Pull-Based Verification | ||
|
|
||
| A key cost optimization is that the Oracle does not require message-passing infrastructure (like LayerZero or Hyperlane) between chains. Instead: | ||
|
|
||
| - Validators read **historical chain data** on-demand when a caller requests verification | ||
| - Attestations are submitted by the caller to the Relay Chain, meaning **no gas is spent on origin or destination chains** for verification | ||
| - This dramatically reduces the per-order cost of verification compared to protocols that emit and relay crosschain messages |
Collaborator
There was a problem hiding this comment.
maybe redundant as it si already mentioned in overview above
clemsos
reviewed
Mar 2, 2026
| The Oracle is a decentralized validator set that verifies crosschain activity and produces signed attestations for the [Hub](/references/protocol/components/hub) on the [Relay Chain](/references/protocol/components/relay-chain). Validators independently read origin and destination chains, verify that deposits and fills occurred correctly, and sign EIP-712 attestations. Attestations require signatures from a threshold of validators before the Hub will accept them. | ||
|
|
||
| The Oracle never initiates actions — it only responds to requests. Solvers and users call the Oracle when they need verification, and the Oracle returns signed attestations that the caller then submits to the Hub. This **pull-based** model keeps costs low and avoids the overhead of maintaining persistent message channels to every chain. | ||
|
|
Collaborator
There was a problem hiding this comment.
maybe the overview can clarify that the Oracle has actually two parts :
- the (offchain) oracle service that delivers attestations (i.e. witness what already happened on chains and returns the relevant cryptographic signed messages to track these events on the relay Hub)
and - the oracle contract (on relay chain) that is in charge of writing to the Hub contract. It only accept instructions signed by a valid offchain oracle and make sure they can be executed only once.
This makes the description below easier to follow
clemsos
approved these changes
Mar 2, 2026
Collaborator
clemsos
left a comment
clemsos
left a comment
There was a problem hiding this comment.
some small comments but LG !
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Complete rewrite of the Settlement Protocol documentation section: