Updated explainer #1216
Updated explainer #1216
Conversation
✅ Deploy Preview for docs-optimism ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThis pull request introduces comprehensive documentation updates for the OP Stack's interoperability features. The changes include restructuring the navigation metadata, removing the Sequence DiagramsequenceDiagram
participant SourceChain
participant CrossL2Inbox
participant DestinationChain
SourceChain->>CrossL2Inbox: Initiate Cross-Chain Message
CrossL2Inbox-->>DestinationChain: Transmit Message
DestinationChain->>CrossL2Inbox: Validate Message
CrossL2Inbox-->>DestinationChain: Execute Message
Possibly Related PRs
Suggested Reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (9)
pages/stack/interop/_meta.json (1)
3-10: Navigation structure looks good but needs title case consistencyThe navigation items follow a logical structure, but there are inconsistencies in title case usage:
- "Interop predeploys" vs "Interop explainer"
- "Connectivity considerations" vs "Interop message passing"
Consider standardizing the titles to follow consistent capitalization:
{ "explainer": "Interop Explainer", - "predeploy": "Interop predeploys", + "predeploy": "Interop Predeploys", "devnet": "Interop Devnet", "supersim": "Supersim Multichain Development Environment", - "message-passing": "Interop message passing", + "message-passing": "Interop Message Passing", "op-supervisor": "OP Supervisor", "assets": "Assets", - "connectivity": "Connectivity considerations", - "security": "Security considerations" + "connectivity": "Connectivity Considerations", + "security": "Security Considerations" }pages/stack/interop/connectivity.mdx (2)
24-26: Grammar and clarity improvements neededThe sentence structure and tense usage need improvement in this paragraph.
Apply these changes for better clarity:
- This happens when the transaction consumes more than the gas limit of the smaller chain but less than of the bigger chain. At 2024 usages levels, these sorts of transactions are very rare. + This occurs when a transaction consumes more gas than the smaller chain's limit but less than the larger chain's limit. As of 2024, these types of transactions are rare.
30-31: Technical clarity improvement neededThe explanation of callback-style transactions could be clearer and more technically precise.
Consider revising for better technical clarity:
- If two blocks are being built at the same time with shared knowledge of their contents, it is possible to build blocks where a transaction calls to another chain, does compute and then a transaction calls back with the results. + When two blocks are built simultaneously with shared knowledge of their contents, it becomes possible to construct blocks where a transaction calls another chain, performs computation, and receives results through a callback transaction.pages/stack/interop/predeploy.mdx (3)
31-33: Grammar and technical accuracy improvements neededThere are minor grammar issues and the ERC20 token transfer description needs clarification.
Apply these changes:
- It is utilized, among other things, for secure transfers ERC20 tokens between L2 chains. + It is utilized, among other things, for secure transfers of ERC20 tokens between L2 chains.
41-41: Add article for better readabilityThe sentence is missing the article "the" before "functionalities".
- `OptimismSuperchainERC20` is to extend functionalities of the `OptimismMintableERC20` + `OptimismSuperchainERC20` is to extend the functionalities of the `OptimismMintableERC20`🧰 Tools
🪛 LanguageTool
[uncategorized] ~41-~41: You might be missing the article “the” here.
Context: ...OptimismSuperchainERC20is to extend functionalities of theOptimismMintableERC20so that ...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
50-51: Technical documentation improvement neededThe BeaconProxy pattern explanation could be more detailed for better understanding.
Consider expanding the explanation:
- To enable upgrades, `OptimismSuperchainERC20` contracts use [the `BeaconProxy` pattern](https://docs.openzeppelin.com/contracts/3.x/api/proxy#beacon). - This contract is the `Beacon` part, which provides the implementation address for those proxies. + To enable upgrades, `OptimismSuperchainERC20` contracts implement [the `BeaconProxy` pattern](https://docs.openzeppelin.com/contracts/3.x/api/proxy#beacon), a proxy pattern that allows multiple proxy contracts to be upgraded atomically. + This contract serves as the central `Beacon` that stores and provides the implementation address for all proxy instances.pages/stack/interop/security.mdx (2)
24-24: Fix grammatical issues for better clarity.The sentence has missing articles and incorrect word placement.
-if the information provided to sequencer is incorrect, of course the blocks posted by the sequencer will be also incorrect. +if the information provided to the sequencer is incorrect, of course the blocks posted by the sequencer will also be incorrect.🧰 Tools
🪛 LanguageTool
[uncategorized] ~24-~24: Possible missing article found.
Context: ...at case, if the information provided to sequencer is incorrect, of course the blocks post...(AI_HYDRA_LEO_MISSING_THE)
[style] ~24-~24: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...(ALSO_PLACEMENT)
89-89: Fix typo in word "dependencies".-A cross safe block is one that is written to L1, and whose dependecies (direct or indirect, including dependencies of previous blocks in the same chain) are all written to L1. +A cross safe block is one that is written to L1, and whose dependencies (direct or indirect, including dependencies of previous blocks in the same chain) are all written to L1.pages/stack/interop/explainer.mdx (1)
149-149: Fix missing word in sentence.-A block *local safe* once it is written to L1. +A block is *local safe* once it is written to L1.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
pages/stack/interop/_meta.json(1 hunks)pages/stack/interop/connectivity.mdx(1 hunks)pages/stack/interop/cross-chain-message.mdx(0 hunks)pages/stack/interop/explainer.mdx(1 hunks)pages/stack/interop/predeploy.mdx(1 hunks)pages/stack/interop/security.mdx(1 hunks)
💤 Files with no reviewable changes (1)
- pages/stack/interop/cross-chain-message.mdx
🧰 Additional context used
📓 Path-based instructions (4)
pages/stack/interop/connectivity.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
pages/stack/interop/security.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
pages/stack/interop/explainer.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
pages/stack/interop/predeploy.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
🪛 LanguageTool
pages/stack/interop/security.mdx
[style] ~21-~21: Consider removing “of” to be more concise
Context: ...e cross safe (written to L1, along with all of the ones on which the block depends) and th...
(ALL_OF_THE)
[uncategorized] ~24-~24: Possible missing article found.
Context: ...at case, if the information provided to sequencer is incorrect, of course the blocks post...
(AI_HYDRA_LEO_MISSING_THE)
[style] ~24-~24: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...
(ALSO_PLACEMENT)
[typographical] ~32-~32: Consider adding a comma after ‘Normally’ for more clarity.
Context: ...are deposit only blocks? Normally the blocks that make it to the canonica...
(RB_LY_COMMA)
[grammar] ~42-~42: Adverb repetition.
Context: ...nsored by the sequencer. A deposit only block only contains the deposit transactions and s...
(ADVERB_VERB_ADVERB_REPETITION)
[uncategorized] ~52-~52: Possible missing comma found.
Context: ...gossip protocol, we have minimal latency but at a security cost (because the source ...
(AI_HYDRA_LEO_MISSING_COMMA)
[formatting] ~53-~53: Consider inserting a comma after an introductory phrase for better readability.
Context: ...source sequencer posts the block to L1. In that case we can be more certain that the block i...
(IN_THAT_CASE_COMMA)
pages/stack/interop/explainer.mdx
[grammar] ~22-~22: Did you mean “other's”?
Context: ...hat lets OP Stack blockchains read each others' state. Interoperability provides the fo...
(EACH_OTHERS)
[style] ~150-~150: Consider removing “of” to be more concise
Context: ...e* when in addition to the block itself all of the blocks on which it depends (directly or...
(ALL_OF_THE)
pages/stack/interop/predeploy.mdx
[uncategorized] ~41-~41: You might be missing the article “the” here.
Context: ... OptimismSuperchainERC20 is to extend functionalities of the OptimismMintableERC20 so that ...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
🔇 Additional comments (3)
pages/stack/interop/security.mdx (1)
136-145: Consider including the commented out content.The commented out sections contain valuable information about censorship resistance and message validation. Consider incorporating this content into the main document, as it provides important context about the security model.
pages/stack/interop/explainer.mdx (2)
32-65: Architecture explanation and diagram are clear and accurate.The section effectively explains the components and their interactions, with the mermaid diagram providing excellent visual support.
193-202: Consider including the commented out interop assets section.The commented out section contains valuable information about the Superchain ERC20 token specification and asset transfer capabilities. Consider incorporating this content into the main document.
|
|
||
| - *Equivocation*. A sequencer publishes a block using the gossip protocol that is different from the one that eventually gets written to L1. | ||
| Equivocation is solved by the distinction between blocks that are cross safe (written to L1, along with all of the ones on which the block depends) and those that aren't. | ||
| - *Faulty information*. The sequencer operator can run a verifier node for every chain in the dependency set, in which case it can deduce the initiating messages from the safe transactions of every chain. |
There was a problem hiding this comment.
this is only for unsafe info - correct?
There was a problem hiding this comment.
Faulty information? No. If the sequencer operator does not run nodes for all the dependency chains, it can have an incorrect block that it thinks is cross-safe. It's not enough that the real information is posted to L1, you need to actually use it to be safe.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
pages/stack/interop/security.mdx (3)
20-24: Improve clarity with grammatical refinements.Consider these grammatical improvements:
- To save on resources, the sequencer can choose to query existing nodes of the source blockchain. - In that case, if the information provided to sequencer is incorrect, of course the blocks posted by the sequencer will be also incorrect. + To save on resources, the sequencer can choose to query existing nodes of the source blockchain. + In that case, if the information provided to the sequencer is incorrect, the blocks posted by the sequencer will also be incorrect.🧰 Tools
🪛 LanguageTool
[style] ~21-~21: Consider removing “of” to be more concise
Context: ...e cross safe (written to L1, along with all of the ones on which the block depends) and th...(ALL_OF_THE)
[style] ~24-~24: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...(ALSO_PLACEMENT)
49-93: LGTM! Consider adding a reference link.The explanation of latency/security tradeoff is clear and well-illustrated with sequence diagrams. Consider adding a link to the detailed transaction finality documentation for more in-depth understanding.
🧰 Tools
🪛 LanguageTool
[formatting] ~53-~53: Consider inserting a comma after an introductory phrase for better readability.
Context: ...source sequencer posts the block to L1. In that case we can be more certain that the block i...(IN_THAT_CASE_COMMA)
89-89: Fix typo in the word "dependencies".-A cross safe block is one that is written to L1, and whose dependecies (direct or indirect, including dependencies of previous blocks in the same chain) are all written to L1. +A cross safe block is one that is written to L1, and whose dependencies (direct or indirect, including dependencies of previous blocks in the same chain) are all written to L1.pages/stack/interop/explainer.mdx (3)
23-23: Fix possessive form of "each other".-*Interoperability* is a set of protocols and services that lets OP Stack blockchains read each others' state. +*Interoperability* is a set of protocols and services that lets OP Stack blockchains read each other's state.🧰 Tools
🪛 LanguageTool
[grammar] ~23-~23: Did you mean “other's”?
Context: ...hat lets OP Stack blockchains read each others' state. Interoperability provides the fo...(EACH_OTHERS)
99-99: Fix typo in the word "interoperates".-Any log event on any chain that inteoperates with the destination can initiate a cross-domain message. +Any log event on any chain that interoperates with the destination can initiate a cross-domain message.
149-149: Fix grammatical error in the sentence.-In interop, [the traditional safe level](https://docs.optimism.io/stack/transactions/transaction-finality#steps-to-finality) of is divided into two types of safety. +In interop, [the traditional safe level](https://docs.optimism.io/stack/transactions/transaction-finality#steps-to-finality) is divided into two types of safety.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
pages/stack/interop/architecture.mdx(2 hunks)pages/stack/interop/explainer.mdx(1 hunks)pages/stack/interop/security.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- pages/stack/interop/architecture.mdx
🧰 Additional context used
📓 Path-based instructions (2)
pages/stack/interop/security.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
pages/stack/interop/explainer.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
🪛 LanguageTool
pages/stack/interop/security.mdx
[style] ~21-~21: Consider removing “of” to be more concise
Context: ...e cross safe (written to L1, along with all of the ones on which the block depends) and th...
(ALL_OF_THE)
[style] ~24-~24: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...
(ALSO_PLACEMENT)
[typographical] ~32-~32: Consider adding a comma after ‘Normally’ for more clarity.
Context: ...are deposit only blocks? Normally the blocks that make it to the canonica...
(RB_LY_COMMA)
[grammar] ~42-~42: Adverb repetition.
Context: ...nsored by the sequencer. A deposit only block only contains the deposit transactions and s...
(ADVERB_VERB_ADVERB_REPETITION)
[formatting] ~53-~53: Consider inserting a comma after an introductory phrase for better readability.
Context: ...source sequencer posts the block to L1. In that case we can be more certain that the block i...
(IN_THAT_CASE_COMMA)
pages/stack/interop/explainer.mdx
[grammar] ~23-~23: Did you mean “other's”?
Context: ...hat lets OP Stack blockchains read each others' state. Interoperability provides the fo...
(EACH_OTHERS)
[uncategorized] ~65-~65: Possible missing article found.
Context: ...ss-domain message, and it is the job of OP-Supervisor to validate that the log eve...
(AI_HYDRA_LEO_MISSING_THE)
[typographical] ~146-~146: Consider adding a comma after ‘Notably’ for more clarity.
Context: ...sages that are executed in that block. Notably this trust assumption is only for *unsa...
(RB_LY_COMMA)
[style] ~151-~151: Consider removing “of” to be more concise
Context: ...e* when in addition to the block itself all of the blocks on which it depends (directly or...
(ALL_OF_THE)
[uncategorized] ~160-~160: Possible missing comma found.
Context: ...interop protocol works via a dependency set which is configured on a per-chain basi...
(AI_HYDRA_LEO_MISSING_COMMA)
[formatting] ~176-~176: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...hain A, and then from chain A to chain C, because there is no direct dependency between B...
(COMMA_BEFORE_BECAUSE)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - docs-optimism
- GitHub Check: Header rules - docs-optimism
- GitHub Check: Pages changed - docs-optimism
🔇 Additional comments (2)
pages/stack/interop/security.mdx (1)
1-5: LGTM!The frontmatter is well-structured with appropriate title and description.
pages/stack/interop/explainer.mdx (1)
160-189: LGTM!The explanation of interop clusters and dependency sets is clear and well-illustrated with appropriate diagrams.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~160-~160: Possible missing comma found.
Context: ...interop protocol works via a dependency set which is configured on a per-chain basi...(AI_HYDRA_LEO_MISSING_COMMA)
[formatting] ~176-~176: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...hain A, and then from chain A to chain C, because there is no direct dependency between B...(COMMA_BEFORE_BECAUSE)
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
pages/stack/interop/predeploy.mdx (2)
4-4: Enhance the description to be more informative.The current description "How it works" is too vague. Consider providing a more descriptive summary that explains the purpose and scope of interoperability predeploys.
-description: How it works. +description: Overview of predeployed smart contracts that enable cross-chain interoperability.
32-32: Fix grammatical error in the sentence.Add the preposition "of" before "ERC20" for correct grammar.
-It is utilized, among other things, for secure transfers ERC20 tokens between L2 chains. +It is utilized, among other things, for secure transfers of ERC20 tokens between L2 chains.🧰 Tools
🪛 LanguageTool
[uncategorized] ~32-~32: Possible missing preposition found.
Context: ...mong other things, for secure transfers ERC20 tokens between L2 chains. Messages sen...(AI_HYDRA_LEO_MISSING_OF)
pages/stack/interop/security.mdx (2)
24-24: Fix grammatical and structural issues.The sentence has multiple issues that affect readability.
-In that case, if the information provided to sequencer is incorrect, of course the blocks posted by the sequencer will be also incorrect. +In that case, if the information provided to the sequencer is incorrect, the blocks posted by the sequencer will also be incorrect.🧰 Tools
🪛 LanguageTool
[uncategorized] ~24-~24: You might be missing the article “the” here.
Context: ...at case, if the information provided to sequencer is incorrect, of course the blocks post...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~24-~24: A comma might be missing here.
Context: ... provided to sequencer is incorrect, of course the blocks posted by the sequencer will...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[style] ~24-~24: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...(ALSO_PLACEMENT)
42-42: Remove redundant adverb.The sentence contains a redundant use of the word "only".
-A deposit only block only contains the deposit transactions and some internal transactions, not the sequencer transactions. +A deposit only block contains only the deposit transactions and some internal transactions, not the sequencer transactions.🧰 Tools
🪛 LanguageTool
[grammar] ~42-~42: Adverb repetition.
Context: ...nsored by the sequencer. A deposit only block only contains the deposit transactions and s...(ADVERB_VERB_ADVERB_REPETITION)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
pages/stack/interop/_meta.json(1 hunks)pages/stack/interop/predeploy.mdx(1 hunks)pages/stack/interop/security.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- pages/stack/interop/_meta.json
🧰 Additional context used
📓 Path-based instructions (2)
pages/stack/interop/security.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
pages/stack/interop/predeploy.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
🪛 LanguageTool
pages/stack/interop/security.mdx
[style] ~21-~21: Consider removing “of” to be more concise
Context: ...e cross safe (written to L1, along with all of the ones on which the block depends) and th...
(ALL_OF_THE)
[uncategorized] ~24-~24: You might be missing the article “the” here.
Context: ...at case, if the information provided to sequencer is incorrect, of course the blocks post...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~24-~24: A comma might be missing here.
Context: ... provided to sequencer is incorrect, of course the blocks posted by the sequencer will...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[style] ~24-~24: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...
(ALSO_PLACEMENT)
[typographical] ~32-~32: Consider adding a comma after ‘Normally’ for more clarity.
Context: ...are deposit only blocks? Normally the blocks that make it to the canonica...
(RB_LY_COMMA)
[grammar] ~42-~42: Adverb repetition.
Context: ...nsored by the sequencer. A deposit only block only contains the deposit transactions and s...
(ADVERB_VERB_ADVERB_REPETITION)
[formatting] ~53-~53: Consider inserting a comma after an introductory phrase for better readability.
Context: ...source sequencer posts the block to L1. In that case we can be more certain that the block i...
(IN_THAT_CASE_COMMA)
pages/stack/interop/predeploy.mdx
[uncategorized] ~32-~32: Possible missing preposition found.
Context: ...mong other things, for secure transfers ERC20 tokens between L2 chains. Messages sen...
(AI_HYDRA_LEO_MISSING_OF)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - docs-optimism
- GitHub Check: Header rules - docs-optimism
- GitHub Check: Pages changed - docs-optimism
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
pages/stack/interop/security.mdx (1)
26-28: Improve grammar for clarity.Consider these refinements:
-The sequencer operator can run a verifier node for every chain in the dependency set, in which case it can deduce the initiating messages from the safe transactions of every chain. To save on resources, the sequencer can choose to query existing nodes of the source blockchain. In that case, if the information provided to sequencer is incorrect, of course the blocks posted by the sequencer will be also incorrect. +The sequencer operator can run a verifier node for every chain in the dependency set, in which case it can deduce the initiating messages from the safe transactions of every chain. To save on resources, the sequencer can choose to query existing nodes of the source blockchain. In that case, if the information provided to the sequencer is incorrect, the blocks posted by the sequencer will also be incorrect.🧰 Tools
🪛 LanguageTool
[uncategorized] ~28-~28: Possible missing article found.
Context: ...at case, if the information provided to sequencer is incorrect, of course the blocks post...(AI_HYDRA_LEO_MISSING_THE)
[style] ~28-~28: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...(ALSO_PLACEMENT)
pages/stack/interop/explainer.mdx (1)
26-29: Improve clarity of benefits list.Consider these refinements:
-1-block latency asset movement, removing the problem of capital fragmentation leading to better capital efficiency. +1-block latency asset movement, removing capital fragmentation and improving capital efficiency.🧰 Tools
🪛 LanguageTool
[uncategorized] ~26-~26: Possible missing preposition found.
Context: ... following benefits: - 1-block latency asset movement, removing the problem of capit...(AI_HYDRA_LEO_MISSING_IN)
[uncategorized] ~26-~26: Possible missing comma found.
Context: ...vement, removing the problem of capital fragmentation leading to better capital efficiency. -...(AI_HYDRA_LEO_MISSING_COMMA)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
pages/stack/interop/_meta.json(1 hunks)pages/stack/interop/explainer.mdx(1 hunks)pages/stack/interop/security.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- pages/stack/interop/_meta.json
🧰 Additional context used
📓 Path-based instructions (2)
pages/stack/interop/explainer.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
pages/stack/interop/security.mdx (1)
Pattern **/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
- For H1, H2, and H3 headers:
- Use sentence case, capitalizing only the first word.
- Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
- Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
- Flag any headers that seem to inconsistently apply these rules for manual review.
- When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
"
🪛 LanguageTool
pages/stack/interop/explainer.mdx
[grammar] ~23-~23: Did you mean “other's”?
Context: ...hat lets OP Stack blockchains read each others' state. Interoperability provides the fo...
(EACH_OTHERS)
[uncategorized] ~26-~26: Possible missing preposition found.
Context: ... following benefits: - 1-block latency asset movement, removing the problem of capit...
(AI_HYDRA_LEO_MISSING_IN)
[uncategorized] ~26-~26: Possible missing comma found.
Context: ...vement, removing the problem of capital fragmentation leading to better capital efficiency. -...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~65-~65: Possible missing article found.
Context: ...ss-domain message, and it is the job of OP-Supervisor to validate that the log eve...
(AI_HYDRA_LEO_MISSING_THE)
[typographical] ~171-~171: Consider adding a comma after ‘Notably’ for more clarity.
Context: ...s on the block in chain B.
(RB_LY_COMMA)
[style] ~176-~176: Consider removing “of” to be more concise
Context: ...e* when in addition to the block itself all of the blocks on which it depends (directly or...
(ALL_OF_THE)
[uncategorized] ~185-~185: Possible missing comma found.
Context: ...interop protocol works via a dependency set which is configured on a per-chain basi...
(AI_HYDRA_LEO_MISSING_COMMA)
[formatting] ~201-~201: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...hain A, and then from chain A to chain C, because there is no direct dependency between B...
(COMMA_BEFORE_BECAUSE)
pages/stack/interop/security.mdx
[uncategorized] ~28-~28: Possible missing article found.
Context: ...at case, if the information provided to sequencer is incorrect, of course the blocks post...
(AI_HYDRA_LEO_MISSING_THE)
[style] ~28-~28: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...urse the blocks posted by the sequencer will be also incorrect. Note that in this case th...
(ALSO_PLACEMENT)
[typographical] ~36-~36: Consider adding a comma after ‘Normally’ for more clarity.
Context: ...are deposit only blocks? Normally the blocks that make it to the canonica...
(RB_LY_COMMA)
[grammar] ~46-~46: Adverb repetition.
Context: ...nsored by the sequencer. A deposit only block only contains the deposit transactions and s...
(ADVERB_VERB_ADVERB_REPETITION)
[formatting] ~57-~57: Consider inserting a comma after an introductory phrase for better readability.
Context: ...source sequencer posts the block to L1. In that case we can be more certain that the block i...
(IN_THAT_CASE_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - docs-optimism
- GitHub Check: Header rules - docs-optimism
- GitHub Check: Pages changed - docs-optimism
🔇 Additional comments (6)
pages/stack/interop/security.mdx (4)
1-5: LGTM! Clear and objective metadata.The frontmatter is well-structured with appropriate title and description.
18-19: LGTM! Clear explanation of the vulnerability model.The explanation of interop vulnerabilities and the oracle problem is technically accurate and well-structured.
32-50: LGTM! Comprehensive explanation of deposit only blocks.The explanation clearly distinguishes between sequencer and deposit transactions, providing good context for understanding the fallback mechanism.
🧰 Tools
🪛 LanguageTool
[typographical] ~36-~36: Consider adding a comma after ‘Normally’ for more clarity.
Context: ...are deposit only blocks? Normally the blocks that make it to the canonica...(RB_LY_COMMA)
[grammar] ~46-~46: Adverb repetition.
Context: ...nsored by the sequencer. A deposit only block only contains the deposit transactions and s...(ADVERB_VERB_ADVERB_REPETITION)
53-89: LGTM! Clear explanation of the latency/security tradeoff.The section effectively explains the tradeoff between minimal latency and security, with a helpful sequence diagram illustrating the potential issues with unsafe messages.
🧰 Tools
🪛 LanguageTool
[formatting] ~57-~57: Consider inserting a comma after an introductory phrase for better readability.
Context: ...source sequencer posts the block to L1. In that case we can be more certain that the block i...(IN_THAT_CASE_COMMA)
pages/stack/interop/explainer.mdx (2)
16-24: LGTM! Clear explanation of interoperability necessity.The explanation effectively connects the oracle problem to the need for interoperability in the OP Stack.
🧰 Tools
🪛 LanguageTool
[grammar] ~23-~23: Did you mean “other's”?
Context: ...hat lets OP Stack blockchains read each others' state. Interoperability provides the fo...(EACH_OTHERS)
31-67: LGTM! Clear architecture explanation.The section effectively explains the role of OP Supervisor and its interaction with other components, supported by a clear diagram.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~65-~65: Possible missing article found.
Context: ...ss-domain message, and it is the job of OP-Supervisor to validate that the log eve...(AI_HYDRA_LEO_MISSING_THE)
| ## L2ToL2CrossDomainMessenger | ||
|
|
||
| The `L2ToL2CrossDomainMessenger` is a higher level abstraction on top of the `CrossL2Inbox` that provides general message passing. | ||
| It is utilized, among other things, for secure transfers ERC20 tokens between L2 chains. |
There was a problem hiding this comment.
| It is utilized, among other things, for secure transfers ERC20 tokens between L2 chains. | |
| It's utilized for secure ERC20 token transfers between L2 chains. |
There was a problem hiding this comment.
Either the above suggestion, or explain "among other things"
|
|
||
|
|
||
| {/* | ||
| ## What is stopping a sequencer from censoring a cross-chain message? |
There was a problem hiding this comment.
@zainbacchus just want to raise that we should make absolutely certain we uncomment these sections once released
|
|
||
| ## The trust model | ||
|
|
||
| The vulnerability in interop is what happens when there appears to be an initiating message, and therefore we process the executing message, but then it turns out the initiating message is not there in the cannonical chain. |
There was a problem hiding this comment.
| The vulnerability in interop is what happens when there appears to be an initiating message, and therefore we process the executing message, but then it turns out the initiating message is not there in the cannonical chain. | |
| This interop vulnerability arises when an initiating message seems to exist, prompting the processing of the executing message. However, the initiating message ends up not actually appear in the canonical chain. |
| ## The trust model | ||
|
|
||
| The vulnerability in interop is what happens when there appears to be an initiating message, and therefore we process the executing message, but then it turns out the initiating message is not there in the cannonical chain. | ||
| Barring L1 reorgs, there are two ways this can happen: |
There was a problem hiding this comment.
| Barring L1 reorgs, there are two ways this can happen: | |
| Excluding L1 reorgs, this can happen in two ways: |
| To save on resources, the sequencer can choose to query existing nodes of the source blockchain. | ||
| In that case, if the information provided to sequencer is incorrect, of course the blocks posted by the sequencer will be also incorrect. | ||
|
|
||
| Note that in this case the blocks posted by the sequencer will be invalid, and other verifiers will be able to see they are invalid and replace them with *deposit only* blocks. |
There was a problem hiding this comment.
| Note that in this case the blocks posted by the sequencer will be invalid, and other verifiers will be able to see they are invalid and replace them with *deposit only* blocks. | |
| In this case, invalid blocks will be replaced with deposit only blocks by other verifiers. |
There was a problem hiding this comment.
This was fairly confusing. My suggestion doesn't have to be the fix, but we should shorten and clarify.
| @@ -44,7 +44,7 @@ graph LR | |||
| ``` | |||
|
|
|||
| OP-Supervisor holds a database of all the log events of all the chains in the interoperability cluster. | |||
| Every event can potentially initiate a cross domain message, and it is the job of OP-Supervisor to validate that the log event really happened on the source chain. | |||
| Every event can potentially initiate a cross-domain message, and it is the job of OP-Supervisor to validate that the log event really happened on the source chain. | |||
There was a problem hiding this comment.
| Every event can potentially initiate a cross-domain message, and it is the job of OP-Supervisor to validate that the log event really happened on the source chain. | |
| Every event can potentially initiate a cross-domain message, and it's the job of OP-Supervisor to validate that the log event really happened on the source chain. |
|
|
||
| ### Unsafe initiating messages | ||
|
|
||
| L2 blocks start as unsafe, meaning that there is no L1 evidence for them, and the sequencer for that blockchain can send out incorrect information. |
There was a problem hiding this comment.
| L2 blocks start as unsafe, meaning that there is no L1 evidence for them, and the sequencer for that blockchain can send out incorrect information. | |
| L2 blocks start as unsafe, meaning that there's no L1 evidence for them, and the sequencer for that blockchain can send out incorrect information. |
| Alternatively, a sequencer can be configured to only accept executing messages once the initiating message is in a cross safe block. | ||
| A cross safe block is one that is written to L1, and whose dependecies (direct or indirect, including dependencies of previous blocks in the same chain) are all written to L1. | ||
|
|
||
| When a block is cross safe, the source sequencer cannot equivocate, and the state will only need to be recalculated if there is an [L1 reorg](https://www.alchemy.com/overviews/what-is-a-reorg#what-happens-to-reorgs-after-the-merge). |
There was a problem hiding this comment.
| When a block is cross safe, the source sequencer cannot equivocate, and the state will only need to be recalculated if there is an [L1 reorg](https://www.alchemy.com/overviews/what-is-a-reorg#what-happens-to-reorgs-after-the-merge). | |
| When a block is cross safe, the source sequencer cannot equivocate, and the state will only need to be recalculated if there's an [L1 reorg](https://www.alchemy.com/overviews/what-is-a-reorg#what-happens-to-reorgs-after-the-merge). |
| <summary>What are deposit only blocks?</summary> | ||
|
|
||
| Normally the blocks that make it to the canonical blockchain are those posted to L1 by the sequencer. | ||
| However, when those blocks are missing or invalid (for example because they rely on an initiating message that is missing), they are replaced by *deposit only blocks*, blocks whose content can be calculated from L1 without relying on the sequencer. |
There was a problem hiding this comment.
| However, when those blocks are missing or invalid (for example because they rely on an initiating message that is missing), they are replaced by *deposit only blocks*, blocks whose content can be calculated from L1 without relying on the sequencer. | |
| However, when those blocks are missing or invalid (for example because they rely on an initiating message that is missing), they're replaced by *deposit only blocks*, blocks whose content can be calculated from L1 without relying on the sequencer. |
|
|
||
| The following predeploys have been added to enable interoperability. | ||
| *Predeployed smart contracts* exist at predetermined addresses, coming from the genesis state. | ||
| They are similar to [precompiles](https://www.evm.codes/precompiled) but run directly in the EVM instead of running as native code. |
There was a problem hiding this comment.
| They are similar to [precompiles](https://www.evm.codes/precompiled) but run directly in the EVM instead of running as native code. | |
| They're similar to [precompiles](https://www.evm.codes/precompiled) but run directly in the EVM instead of running as native code. |
| @@ -1,10 +1,10 @@ | |||
| { | |||
| "explainer": "Interop explainer", | |||
| "architecture": "Architecture", | |||
There was a problem hiding this comment.
Let's make sure we set up a redirect for the now missing Architecture page
There was a problem hiding this comment.
Actually, we're not actually deleting this page. Why are we removing it from the nav?
| "devnet": "Interop devnet", | ||
| "supersim": "Supersim Multichain Development Environment", | ||
| "cross-chain-message": "Anatomy of cross-chain message", |
Factory is not part of scope. See #1216 where factory is removed from redeploy list
Description
Tests
N/A
Additional context
N/A
Metadata
N/A