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
previously 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 !
julien51
reviewed
Mar 5, 2026
|
|
||
| 1. **Solver initiates withdrawal** — The solver transfers their [Hub](/references/protocol/components/hub) balance to a deterministic [withdrawal address](/references/protocol/components/hub#withdrawal-addresses) that encodes the withdrawal parameters (target chain, asset, amount, recipient) | ||
|
|
||
| 2. **Oracle detects transfer** — The [Oracle](/references/protocol/components/oracle) monitors the Hub for transfers to withdrawal addresses, decodes the parameters, and forwards the request to the Allocator |
Member
There was a problem hiding this comment.
Not sure that's a blocker but that is work that is being done by @georgeroman and not completely shipped :) We are still using a pernissioned role right now.
julien51
reviewed
Mar 5, 2026
| Depository-->>Solver: Funds released | ||
| ``` | ||
|
|
||
| The withdrawal authorization process: |
Member
There was a problem hiding this comment.
Maybe a note that this is not solver-specific. any address that holds a balance of any token on the hub can withdraw using the same mechanism
julien51
reviewed
Mar 5, 2026
|
|
||
| ## Overview | ||
|
|
||
| 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. |
Member
There was a problem hiding this comment.
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) contracts (or addresses on chains without 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. |
julien51
reviewed
Mar 5, 2026
| Key properties: | ||
|
|
||
| - **No single key holder** — The private key is split across multiple MPC nodes, and a threshold must cooperate to produce a signature | ||
| - **Programmable authorization** — The Allocator enforces rules (balance checks, rate limits) before requesting any signature |
Member
There was a problem hiding this comment.
Suggested change
| - **Programmable authorization** — The Allocator enforces rules (balance checks, rate limits) before requesting any signature | |
| - **Programmable authorization** — The Allocator enforces rules (balance checks) before requesting any signature |
julien51
reviewed
Mar 5, 2026
Comment on lines
+9
to
+11
| Deposit Addresses allow users to bridge funds by sending tokens to a pre-computed address — no wallet connection, no calldata, and no approval transactions required. Under the hood, Relay uses **counterfactual smart contracts** to generate deterministic deposit addresses for each order. Funds sent to these addresses are swept into the [Depository](/references/protocol/components/depository) and attributed to the correct order. | ||
|
|
||
| This is powered by two contracts: a **DepositFactory** (deployed once per chain) and a **DepositSweeper** (a stateless implementation contract that proxies delegate to). |
Member
There was a problem hiding this comment.
This is the EVM way... Solana is slightly different abd Bitcoin is very different. Not sure that's a problem but maybe worth clarifying!
julien51
reviewed
Mar 5, 2026
Comment on lines
+64
to
+65
| - **`deployAndSweep(orderId, depositor, tokens)`** — Deploys the proxy (if needed) and sweeps all specified tokens to the Depository. The `tokens` array supports sweeping multiple token types in a single transaction. | ||
| - **`sweep(orderId, depositor, tokens)`** — Sweeps funds from an already-deployed proxy. Used for re-sweeping if additional funds arrive after the initial sweep. |
Member
There was a problem hiding this comment.
We only have a single sweep call now which desploys if needed. simpler.
julien51
reviewed
Mar 5, 2026
|
|
||
| ## Contracts | ||
|
|
||
| ### DepositFactory |
Member
There was a problem hiding this comment.
Different name. DepositAddressFactory
julien51
reviewed
Mar 5, 2026
| - **DEPOSITORY** — The Depository contract on that chain | ||
| - **IMPLEMENTATION** — The DepositSweeper implementation contract | ||
|
|
||
| ### DepositSweeper |
julien51
reviewed
Mar 5, 2026
|
|
||
| The Depository is a smart contract deployed on every chain that Relay supports. It serves as the entry point for user funds — accepting deposits and releasing withdrawals when authorized by the [Allocator](/references/protocol/components/allocator). | ||
|
|
||
| There are currently 80+ Depository contracts deployed, one per supported chain. Each contract is **non-upgradable**, meaning its logic cannot be changed after deployment. See [Contract Addresses](/references/protocol/addresses) for the full list. |
Member
There was a problem hiding this comment.
Maybe worth mentnionning that on Bitcoin that's MPC
julien51
reviewed
Mar 5, 2026
| </Warning> | ||
|
|
||
| ## Security | ||
|
|
Member
There was a problem hiding this comment.
We should mention there is an owner and that is the Security Council multisig!
julien51
reviewed
Mar 5, 2026
| - When a solver **fills** an order, the Oracle attests this, and the Hub **transfers** the balance from the user to the solver | ||
| - When a solver **withdraws**, they transfer their balance to a [withdrawal address](#withdrawal-addresses) on the Hub. After funds are claimed from the Depository, the Oracle attests the withdrawal and the Hub **burns** the corresponding balance | ||
|
|
||
| This means the Hub always reflects the current state of all funds across all chains in real-time. |
Member
There was a problem hiding this comment.
Not so real-time because it needs oracle attestations
julien51
reviewed
Mar 5, 2026
|
|
||
| ### Forced Exits | ||
|
|
||
| If a solver fails to fill **and** doesn't refund, the user can request a forced exit attestation after the order's fill window expires. The Oracle verifies the fill did not occur and returns a signed attestation. The user submits this to the Hub to restore their balance and reclaim their deposit. |
Member
There was a problem hiding this comment.
Hum, I think we should rethink this part. The oracle cannot witness that something did not occur.
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
4 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: