Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Transaction Finality Explainer #987

Open
wants to merge 58 commits into
base: main
Choose a base branch
from
Open

Transaction Finality Explainer #987

wants to merge 58 commits into from

Conversation

krofax
Copy link
Contributor

@krofax krofax commented Oct 14, 2024

Description

Created a section on the docs to cover the nuances of transaction finality, sequencer policy and challenge periods to debunk the belief that OP Stack chains take 7 days for transaction finalization.

Tests

Additional context

Metadata

Include a link to any github issues that this may close in the following form:

@krofax krofax requested a review from a team as a code owner October 14, 2024 10:28
Copy link

netlify bot commented Oct 14, 2024

Deploy Preview for docs-optimism ready!

Name Link
🔨 Latest commit 1186141
🔍 Latest deploy log https://app.netlify.com/sites/docs-optimism/deploys/672cd49a23a9f30008496d77
😎 Deploy Preview https://deploy-preview-987--docs-optimism.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

Copy link
Contributor

coderabbitai bot commented Oct 14, 2024

Walkthrough

This pull request introduces a new documentation page titled transaction-finality.mdx, which explains the concept of transaction finality within OP Stack chains. It outlines the process by which transactions become finalized, clarifies misconceptions about finality durations, and distinguishes finality from withdrawal wait times. Additionally, a new entry is added to the _meta.json file for this documentation, and the structure of the transactions.mdx file is modified to include the new finality card and reorganize existing cards for better clarity.

Changes

File Path Change Summary
pages/stack/transactions/transaction-finality.mdx New file added to document transaction finality in OP Stack chains.
pages/stack/transactions/_meta.json New key-value pair added for transaction finality.
pages/stack/transactions.mdx Updated card layout: added "Transaction finality OP Stack" card, and repositioned existing cards.

Assessment against linked issues

Objective Addressed Explanation
New docs page covering tx finality and debunking the 7-day finalization myth (#942)

Possibly related PRs

  • Details on the sequencer fee vault #858: The changes in this PR detail the Sequencer Fee Vault, which is relevant to transaction finality as it discusses the management of transaction fees that are integral to the finalization process on OP Stack chains.
  • Add cross-domain section #1027: This PR introduces a new section on Cross Domain Transactions, which relates to transaction finality by explaining the lifecycle of transactions that involve interactions between Layer 1 and Layer 2, including aspects of finality in cross-chain contexts.

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?

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Generate unit testing code for this file.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai generate unit testing code for this file.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and generate unit testing code.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

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)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Outside diff range and nitpick comments (1)
pages/stack/protocol/rollup/finality.mdx (1)

1-87: Excellent documentation on transaction finality.

This document provides a comprehensive and well-structured explanation of transaction finality in Ethereum and OP Stack. The content is informative, clear, and adheres to the provided coding guidelines. The use of Callout components and bullet points enhances readability and helps to highlight important information.

As a final step, I recommend a thorough proofread of the entire document to catch any minor issues that might have been overlooked. Pay special attention to the grammar correction suggested earlier in the "Finality on Ethereum" section.

🧰 Tools
🪛 LanguageTool

[grammar] ~17-~17: With the plural noun ‘transactions’, the verb inflection ‘achieves’ is not correct.
Context: ...rk conditions, transactions on Ethereum achieves finality in about 15 minutes. * Conse...

(NNS_IN_NNP_VBZ)


[uncategorized] ~46-~46: The preposition ‘of’ seems more likely in this position.
Context: ...hereum to establish a view of the state on an OP Stack chain: * Rollup nodes po...

(AI_HYDRA_LEO_REPLACE_ON_OF)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Files that changed from the base of the PR and between 861c96d and 0b36071.

⛔ Files ignored due to path filters (1)
  • public/img/op-stack/protocol/tx-finality.png is excluded by !**/*.png
📒 Files selected for processing (2)
  • pages/stack/protocol/rollup/finality.mdx (1 hunks)
  • words.txt (1 hunks)
✅ Files skipped from review due to trivial changes (1)
  • words.txt
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/protocol/rollup/finality.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 headers, 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).
  • Use sentence case for H1, H2, and H3 headers, capitalizing only the first word and any proper nouns.
  • For all headers (H1, H2, H3), do not change the capitalization of proper nouns; keep them as they are.
    "
🪛 LanguageTool
pages/stack/protocol/rollup/finality.mdx

[grammar] ~17-~17: With the plural noun ‘transactions’, the verb inflection ‘achieves’ is not correct.
Context: ...rk conditions, transactions on Ethereum achieves finality in about 15 minutes. * Conse...

(NNS_IN_NNP_VBZ)


[uncategorized] ~46-~46: The preposition ‘of’ seems more likely in this position.
Context: ...hereum to establish a view of the state on an OP Stack chain: * Rollup nodes po...

(AI_HYDRA_LEO_REPLACE_ON_OF)

🔇 Additional comments (5)
pages/stack/protocol/rollup/finality.mdx (5)

1-11: LGTM: Metadata and introduction are well-structured and informative.

The metadata provides clear information about the document's content, and the introduction offers a concise definition of transaction finality. The language used is appropriate and adheres to the provided guidelines.


27-42: LGTM: Clear explanation of OP Stack finality.

This section effectively explains how OP Stack derives security from Ethereum and clearly defines the three stages of finality. The use of the Callout component adds valuable information about the OP Stack's security measures.


44-52: LGTM: Clear explanation of the settlement layer.

This section effectively explains how Ethereum establishes a view of the state on an OP Stack chain. The use of bullet points helps in presenting the information clearly.

Regarding the static analysis suggestion to replace "on" with "of" in the phrase "state on an OP Stack chain", the current preposition "on" is correct and more appropriate in this context. It accurately conveys the idea of the state existing on the OP Stack chain, rather than being a property of it.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~46-~46: The preposition ‘of’ seems more likely in this position.
Context: ...hereum to establish a view of the state on an OP Stack chain: * Rollup nodes po...

(AI_HYDRA_LEO_REPLACE_ON_OF)


54-62: LGTM: Clear explanation of sequencer reliability.

This section effectively addresses concerns about centralized sequencers and explains how consensus rules and network nodes ensure reliability. The information is presented clearly and concisely using bullet points.


64-87: LGTM: Comprehensive explanation of the challenge period.

This section provides a clear and detailed explanation of the 7-day withdrawal challenge period in OP Stack rollups. It effectively clarifies the distinction between transaction finality and the challenge period, which is crucial for understanding the system. The use of bullet points and the Callout component enhances the presentation of this complex information.

pages/stack/protocol/rollup/finality.mdx Outdated Show resolved Hide resolved
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Outside diff range and nitpick comments (1)
pages/stack/protocol/rollup/_meta.json (1)

6-6: Remove trailing space in "Transaction Finality "

There's an extra space at the end of the value for the "transaction-finality" key. While this won't affect functionality, it's best to remove it for consistency and cleanliness.

Here's the suggested change:

-    "transaction-finality": "Transaction Finality ",
+    "transaction-finality": "Transaction Finality",
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Files that changed from the base of the PR and between 0b36071 and 880a3eb.

📒 Files selected for processing (2)
  • pages/stack/protocol/rollup/_meta.json (1 hunks)
  • pages/stack/protocol/rollup/finality.mdx (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • pages/stack/protocol/rollup/finality.mdx
🧰 Additional context used
🔇 Additional comments (1)
pages/stack/protocol/rollup/_meta.json (1)

6-6: LGTM: New entry for transaction finality added.

The addition of the "transaction-finality" entry aligns well with the PR objectives to enhance documentation on transaction finality in the OP Stack. Its placement in the file is logical within the context of the rollup process flow.

@sahilkamra2
Copy link

I have a doubt regarding the explanation posted above:
Quoting from the explanation.
"The 7 day challenge window is to ensure there’s sufficient time for someone to dispute the withdrawal claim. The challenge game relies on the L2 tx history to discern whether the withdrawal claim is valid or not." - I feel this statement doesn't capture the full essence of Fault proofs.

As far as I understand optimistic rollups:

  • 7 day challenge window is to ensure that the batch being posted to Ethereum by op-batcher has correct transaction. (What happens in case of a 51% attack? where all nodes DONOT follow the consensus rules like Bitcoin) ?
  • Disputing withdrawal claims is separate as op-batcher is bypassed in that process that can also be disputed using FP.

Quoting docs "The transaction needs to be written to L1 (Ethereum). This is typically performed by op-batcher, but any user can send an L1 transaction to submit an L2 transaction, in which case op-batcher is bypassed."

Again quoting from the explanation:
A successful challenge (aka a failed withdrawal claim) would have no impact on the state of the L2 and would not cause a reorg. A successful challenge is focused on discerning whether the claim is valid or not based on the historical L2 txs.

A successful challenge can also be for a batch that has been posted not necessarily withdrawals. (A batch is posted every 10 minutes) and would definitely cause a reorg- as far as I understand.

@zainbacchus @sbvegan can you confirm If I am correct?

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Outside diff range and nitpick comments (4)
pages/stack/protocol/rollup/finality.mdx (4)

12-12: Avoid using personal pronouns in technical documentation.

Replace "we" with a more formal tone to maintain consistency in communal documentation.

-OP Stack rollup is an extension of the consensus mechanism in Ethereum, where instead of running an entirely separate consensus protocol, we piggyback off Ethereum's consensus.
+OP Stack rollup is an extension of the consensus mechanism in Ethereum, where instead of running an entirely separate consensus protocol, it leverages Ethereum's consensus.

93-93: Remove unnecessary comma.

There's an unnecessary comma after "proof system".

-The proof system, is entirely separate from the core OP Stack protocol.
+The proof system is entirely separate from the core OP Stack protocol.

135-135: Remove redundant wording in conclusion.

The phrase "additional layer" is redundant.

-Transaction finality on the OP Stack depends heavily on Ethereum's consensus mechanism. The OP Stack ensures that rollups inherit Ethereum's finality guarantees, while the proof system adds an additional layer of validation for app-level functionality.
+Transaction finality on the OP Stack depends heavily on Ethereum's consensus mechanism. The OP Stack ensures that rollups inherit Ethereum's finality guarantees, while the proof system adds a layer of validation for app-level functionality.
🧰 Tools
🪛 LanguageTool

[style] ~135-~135: This phrase might be redundant. Consider either removing or replacing the adjective ‘additional’.
Context: ...lity guarantees, while the proof system adds an additional layer of validation for app-level functionali...

(ADD_AN_ADDITIONAL)


97-97: Provide more context for state hash example.

The example using XYZ as a state hash is not very informative. Consider using a more realistic example.

-A claim in the context of rollups built on the OP Stack is a statement that asserts the state of the system at a specific block height. For example, a claim might assert that at block 1,000,000, the state hash is `XYZ`.
+A claim in the context of rollups built on the OP Stack is a statement that asserts the state of the system at a specific block height. For example, a claim might assert that at block 1,000,000, the state hash is `0x1234...abcd`.
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Files that changed from the base of the PR and between 880a3eb and f35ba6c.

📒 Files selected for processing (1)
  • pages/stack/protocol/rollup/finality.mdx (1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/protocol/rollup/finality.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 headers, 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).
  • Use sentence case for H1, H2, and H3 headers, capitalizing only the first word and any proper nouns.
  • For all headers (H1, H2, H3), do not change the capitalization of proper nouns; keep them as they are.
    "
🪛 LanguageTool
pages/stack/protocol/rollup/finality.mdx

[grammar] ~22-~22: The verb after “to” should be in the base form as part of the to-infinitive. A verb can take many forms, but the base form is always used in the to-infinitive.
Context: ...ability and ordering are fundamental to ensuring the integrity of the system. ## Consen...

(TO_NON_BASE)


[grammar] ~28-~28: Are you sure this verb form is correct? The progressive tense may be more appropriate here.
Context: ...nsaction ordering and finality. ## Why piggybacking on Ethereum? By publishing rollup bloc...

(MISSING_IS)


[uncategorized] ~34-~34: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...of this approach include: * OP Stack inherit Ethereum's security and ordering proper...

(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)


[uncategorized] ~46-~46: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ...ansaction. * Finalized: Transactions is finalized once more than (>65) L1 block...

(AI_HYDRA_LEO_CPT_IS_ARE)


[uncategorized] ~89-~89: You might be missing the article “a” here.
Context: ...same transactions 4. System returns to consistent state after reprocessing ## The role o...

(AI_EN_LECTOR_MISSING_DETERMINER_A)


[uncategorized] ~116-~116: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...tive value of the bridged assets. ## 7 days challenge period in OP Stack The 7 day...

(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)


[uncategorized] ~118-~118: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...ays challenge period in OP Stack The 7 days challenge period exists to give time fo...

(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)


[uncategorized] ~122-~122: When a number forms part of an adjectival compound, use a hyphen.
Context: ...fects the system. ### Why 7 days? The 7 day period is a reasonable time frame to al...

(MISSING_HYPHEN)


[style] ~135-~135: This phrase might be redundant. Consider either removing or replacing the adjective ‘additional’.
Context: ...lity guarantees, while the proof system adds an additional layer of validation for app-level functionali...

(ADD_AN_ADDITIONAL)

pages/stack/protocol/rollup/finality.mdx Outdated Show resolved Hide resolved
pages/stack/protocol/rollup/finality.mdx Outdated Show resolved Hide resolved
pages/stack/protocol/rollup/finality.mdx Outdated Show resolved Hide resolved
pages/stack/protocol/rollup/finality.mdx Outdated Show resolved Hide resolved
pages/stack/protocol/rollup/finality.mdx Outdated Show resolved Hide resolved
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Outside diff range and nitpick comments (6)
pages/stack/transactions/_meta.json (1)

6-6: Maintain consistent capitalization and naming conventions.

  1. The title "Transaction finality" should be capitalized as "Transaction Finality" to match the capitalization pattern of other entries (e.g., "Transaction Fees", "Transaction Flow").
  2. Consider using camelCase for the key to match the existing pattern (e.g., "transactionFinality" instead of "transaction-finality").

Apply this diff to maintain consistency:

-    "transaction-finality":"Transaction finality",
+    "transactionFinality": "Transaction Finality",
words.txt (1)

305-305: Consider adding transaction finality related terms.

While the current additions are good, consider adding these relevant terms to support the transaction finality documentation:

  • finality
  • challenge-period
  • sequencer-policy
  • fault-proof
  • withdrawal-window

These terms appear to be central to the concepts being documented in the PR.

Would you like me to provide a properly formatted diff with these additions?

🧰 Tools
🪛 LanguageTool

[duplication] ~305-~305: Möglicher Tippfehler: ein Wort wird wiederholt
Context: ... REQUIREDBLOCKS requiredblocks rollouts Rollups rollups Routescan rpckind RPCPREFIX rpcprefix r...

(GERMAN_WORD_REPEAT_RULE)

pages/stack/transactions/transaction-finality.mdx (4)

1-5: Enhance the description metadata for better SEO and clarity.

The current description is quite brief. Consider expanding it to better explain the unique aspects of OP Stack's transaction finality model and its relationship with Ethereum.

-description: Learn about finality in OP Stack and the steps to achieve transaction settlement.
+description: Learn how OP Stack achieves transaction finality by leveraging Ethereum's consensus mechanism, including the roles of sequencers, fault proofs, and challenge periods.

14-15: Maintain formal tone in technical documentation.

The current phrasing could be more formal while maintaining clarity.

-OP Stack is an extension of Ethereum's consensus mechanism. Instead of running an entirely separate consensus protocol, the OP Stack leverages Ethereum's consensus.
+OP Stack extends Ethereum's consensus mechanism. Rather than implementing a separate consensus protocol, OP Stack utilizes Ethereum's existing consensus.

43-49: Use precise terminology for technical processes.

The sequencer steps could be more technically precise.

-1.  Pre-publishing Distribution:
+1.  Pre-confirmation Distribution:
    *   The sequencer receives transactions from users.
-    *   It creates blocks containing these transactions.
+    *   It constructs blocks containing these transactions.
    *   It distributes these blocks to network nodes before L1 publication.
-    *   Nodes mark these blocks as "unsafe."
+    *   Nodes designate these blocks with "unsafe" status.

75-75: Enhance image accessibility attributes.

The image component should include proper dimensions and a more descriptive alt text.

-<Image src="/img/op-stack/protocol/tx-finality.png" alt="Transaction Finality Diagram." width={0} height={0} sizes="100vw" style={{ width: '100%', height: 'auto' }} quality={100} />
+<Image src="/img/op-stack/protocol/tx-finality.png" alt="Diagram showing the progression of transaction states from Unsafe to Safe to Finalized, with approximate timelines and dependencies on L1 confirmation." width={800} height={600} sizes="100vw" style={{ width: '100%', height: 'auto' }} quality={100} />
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Files that changed from the base of the PR and between f35ba6c and 96d6722.

📒 Files selected for processing (3)
  • pages/stack/transactions/_meta.json (1 hunks)
  • pages/stack/transactions/transaction-finality.mdx (1 hunks)
  • words.txt (2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/transactions/transaction-finality.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 headers, 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).
  • Use sentence case for H1, H2, and H3 headers, capitalizing only the first word and any proper nouns.
  • For all headers (H1, H2, H3), do not change the capitalization of proper nouns; keep them as they are.
    "
🪛 LanguageTool
pages/stack/transactions/transaction-finality.mdx

[grammar] ~111-~111: The usual collocation for “independently” is “of”, not “from”. Did you mean “independently of”?
Context: ...tion-level constructs. * They operate independently from the core OP Stack protocol. * Bridge ...

(INDEPENDENTLY_FROM_OF)


[style] ~140-~140: This phrase might be redundant. Consider either removing or replacing the adjective ‘additional’.
Context: ...lity guarantees, while the proof system adds an additional layer of validation for app-level functionali...

(ADD_AN_ADDITIONAL)

words.txt

[duplication] ~305-~305: Möglicher Tippfehler: ein Wort wird wiederholt
Context: ... REQUIREDBLOCKS requiredblocks rollouts Rollups rollups Routescan rpckind RPCPREFIX rpcprefix r...

(GERMAN_WORD_REPEAT_RULE)

🔇 Additional comments (1)
words.txt (1)

19-19: LGTM!

The term is properly added with consistent casing variations and correct alphabetical sorting.

pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
Copy link
Collaborator

@sbvegan sbvegan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall this is good, you've got the core concepts down. Most of my suggestions are to remove additional context to hone in on the key points we're trying to convey on this page.

pages/stack/transactions/_meta.json Outdated Show resolved Hide resolved
pages/stack/transactions/_meta.json Outdated Show resolved Hide resolved
pages/stack/transactions/_meta.json Outdated Show resolved Hide resolved
pages/stack/transactions/_meta.json Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Outside diff range and nitpick comments (3)
pages/stack/transactions/transaction-finality.mdx (3)

12-12: Enhance the introduction with specific misconceptions.

Consider expanding the introduction to briefly mention the key misconceptions that will be addressed, particularly the 7-day finality myth.

-This guide explains when transactions on OP Stack chains are considered finalized and addresses common misconceptions about transaction finality on the OP Stack.
+This guide explains when transactions on OP Stack chains are considered finalized and addresses common misconceptions, such as the belief that transactions take 7 days to finalize on OP Stack chains.

31-31: Address TODO comment regarding numbers.

This TODO comment needs to be resolved before the documentation is published.

Would you like me to help verify and update the numbers mentioned in the steps to finality section?


33-33: Specify image dimensions.

The image currently has placeholder dimensions (width=0, height=0). Consider specifying appropriate dimensions for optimal rendering.

-<Image src="/img/op-stack/protocol/tx-finality.png" alt="Transaction Finality Diagram." width={0} height={0} sizes="100vw" style={{ width: '100%', height: 'auto' }} quality={100} />
+<Image src="/img/op-stack/protocol/tx-finality.png" alt="Transaction Finality Diagram." width={800} height={600} sizes="100vw" style={{ width: '100%', height: 'auto' }} quality={100} />
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between e755619 and eda6ab7.

📒 Files selected for processing (2)
  • pages/stack/transactions/transaction-finality.mdx (1 hunks)
  • words.txt (5 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/transactions/transaction-finality.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:
    1. Use sentence case, capitalizing only the first word.
    2. 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.
    3. 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/transactions/transaction-finality.mdx

[uncategorized] ~27-~27: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ating that the transaction is in a block but its data has not yet been posted to Eth...

(COMMA_COMPOUND_SENTENCE_2)


[style] ~53-~53: Consider removing “of” to be more concise
Context: ...ETH) creates a bad withdrawal claim for all of the ETH in the bridge. Users would be able ...

(ALL_OF_THE)

words.txt

[duplication] ~2-~2: Möglicher Tippfehler: ein Wort wird wiederholt
Context: ACCOUNTQUEUE accountqueue ACCOUNTSLOTS accountslots ADDI ADDIU ADDU airgap Allnodes Allocs ...

(GERMAN_WORD_REPEAT_RULE)


[duplication] ~395-~395: Möglicher Tippfehler: ein Wort wird wiederholt
Context: ...E verkle VHOSTS vhosts Viem viem Viem's VMDEBUG vmdebug VMODULE vmodule voxel wagmi Warpcast xl...

(GERMAN_WORD_REPEAT_RULE)

🔇 Additional comments (2)
words.txt (2)

2-2: LGTM! The dictionary updates align with documentation needs.

The new terms and case variants are appropriate for the transaction finality documentation context and follow the file's existing patterns.

Also applies to: 33-33, 329-331, 395-395, 409-409

🧰 Tools
🪛 LanguageTool

[duplication] ~2-~2: Möglicher Tippfehler: ein Wort wird wiederholt
Context: ACCOUNTQUEUE accountqueue ACCOUNTSLOTS accountslots ADDI ADDIU ADDU airgap Allnodes Allocs ...

(GERMAN_WORD_REPEAT_RULE)


395-395: Verify apostrophe handling in spell checking tools.

The term "Viem's" contains an apostrophe. Let's verify that this doesn't cause issues with the spell checking tools.

✅ Verification successful

Apostrophe handling in spell checking is properly configured

The verification shows that:

  • Multiple possessive forms with apostrophes already exist in words.txt (e.g., Badgeholder's, Celestia's, Pyth's)
  • The cspell configuration properly includes words.txt as a custom dictionary
  • The spell checker is configured to ignore code blocks and paths where apostrophes might cause false positives
🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check if other possessive forms exist in the dictionary
# and verify the spell checking tool's handling of apostrophes

# Search for other words with apostrophes to confirm this pattern
rg "'.s\b" words.txt

# Check if the spell checking configuration has special handling for apostrophes
fd -t f "spell|dict|lint" . -x grep -l "apostrophe"

Length of output: 77


Script:

#!/bin/bash
# Let's try a different approach to check apostrophe handling

# Check for any words with apostrophes in the dictionary
rg "'" words.txt

# Look for spell checking related configuration files
fd -e json -e yaml -e yml -e config

# Check for any documentation about spell checking
fd README -t f -X cat {}

Length of output: 3588


Script:

#!/bin/bash
# Let's check the spell checking configuration

# Check cspell.json for apostrophe handling settings
cat cspell.json

# Look for any existing words with apostrophes in the configuration
rg -l "allowCompoundWords|words" cspell.json

Length of output: 616

🧰 Tools
🪛 LanguageTool

[duplication] ~395-~395: Möglicher Tippfehler: ein Wort wird wiederholt
Context: ...E verkle VHOSTS vhosts Viem viem Viem's VMDEBUG vmdebug VMODULE vmodule voxel wagmi Warpcast xl...

(GERMAN_WORD_REPEAT_RULE)

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Outside diff range and nitpick comments (1)
pages/stack/transactions/transaction-finality.mdx (1)

31-31: Remove or address the TODO comment.

The TODO comment suggests that some numbers need to be fixed, but it's not clear which numbers need attention.

Would you like me to help verify the numbers or create an issue to track this task?

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between eda6ab7 and 4c88d3a.

📒 Files selected for processing (1)
  • pages/stack/transactions/transaction-finality.mdx (1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/transactions/transaction-finality.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:
    1. Use sentence case, capitalizing only the first word.
    2. 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.
    3. 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/transactions/transaction-finality.mdx

[uncategorized] ~27-~27: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ating that the transaction is in a block but its data has not yet been posted to Eth...

(COMMA_COMPOUND_SENTENCE_2)


[style] ~73-~73: Consider removing “of” to be more concise
Context: ...ETH) creates a bad withdrawal claim for all of the ETH in the bridge. Users would be able ...

(ALL_OF_THE)

🔇 Additional comments (3)
pages/stack/transactions/transaction-finality.mdx (3)

1-13: LGTM! Clear and well-structured introduction.

The frontmatter and introduction effectively set up the document's purpose and scope.


14-21: LGTM! Clear explanation of finality concepts.

The sections effectively explain transaction finality and its relationship with Ethereum's consensus mechanism.


87-89: LGTM! Clear and concise conclusion.

The conclusion effectively reinforces the key concepts about OP Stack's relationship with Ethereum's finality guarantees.

pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Outside diff range and nitpick comments (2)
pages/stack/transactions.mdx (2)

14-26: Maintain consistent spacing between cards.

The spacing between cards is inconsistent. Some cards have one newline, while others have two newlines between them.

Apply this diff to standardize the spacing:

  <Card title="Transactions" href="/stack/transactions/transactions" />

  <Card title="Transaction fees on OP Stack" href="/stack/transactions/fees" />

  <Card title="Transaction finality OP Stack" href="/stack/transactions/transaction-finality" />

  <Card title="Forced transaction" href="/stack/transactions/forced-transaction" />

  <Card title="Cross-Domain" href="/stack/transactions/cross-domain" />

  <Card title="Deposit flow" href="/stack/transactions/deposit-flow" />

  <Card title="Transaction Flow" href="/stack/transactions/transaction-flow" />

  <Card title="Withdrawal flow" href="/stack/transactions/withdrawal-flow" />

14-26: Standardize title case in card titles.

Some card titles use title case while others don't. For consistency:

  • "Transaction Flow" should be "Transaction flow"
  • "Cross-Domain" should be "Cross-domain"

Apply this diff to standardize the titles:

-  <Card title="Cross-Domain" href="/stack/transactions/cross-domain" />
+  <Card title="Cross-domain" href="/stack/transactions/cross-domain" />

-  <Card title="Transaction Flow" href="/stack/transactions/transaction-flow" />
+  <Card title="Transaction flow" href="/stack/transactions/transaction-flow" />
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between 241c587 and c8c3d52.

📒 Files selected for processing (1)
  • pages/stack/transactions.mdx (1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/transactions.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:
    1. Use sentence case, capitalizing only the first word.
    2. 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.
    3. 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.
    "
🔇 Additional comments (1)
pages/stack/transactions.mdx (1)

18-19: LGTM: New transaction finality card aligns with PR objectives.

The addition of the transaction finality card directly addresses the documentation needs outlined in issue #942, helping to clarify misconceptions about the 7-day finality period.

pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
pages/stack/transactions/transaction-finality.mdx Outdated Show resolved Hide resolved
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Outside diff range and nitpick comments (2)
pages/stack/transactions/transaction-finality.mdx (2)

31-31: Remove TODO comment.

The timing information has been reviewed and confirmed by @smartcontracts in the past review comments.

-TODO: Fix this so it has the right numbers

85-85: Enhance clarity of reorg recovery explanation.

The explanation of how OP Stack nodes handle Ethereum reorgs needs to be more precise.

-If Ethereum experiences a reorg, OP Stack chains will attempt a graceful recovery. OP Stack nodes will downgrade **"safe"** transactions to **"unsafe"** if needed, while the Sequencer republishes transaction data to maintain chain continuity.
+If an Ethereum reorganization occurs before finality, OP Stack nodes will:
+1. Downgrade affected **"safe"** transactions to **"unsafe"** status
+2. Allow the Sequencer to republish transaction data to maintain chain continuity
+3. Process the new transaction order based on the reorganized Ethereum blocks
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between c8c3d52 and 45a3248.

📒 Files selected for processing (1)
  • pages/stack/transactions/transaction-finality.mdx (1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/transactions/transaction-finality.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:
    1. Use sentence case, capitalizing only the first word.
    2. 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.
    3. 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/transactions/transaction-finality.mdx

[uncategorized] ~27-~27: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ating that the transaction is in a block but its data has not yet been posted to Eth...

(COMMA_COMPOUND_SENTENCE_2)


[style] ~73-~73: Consider removing “of” to be more concise
Context: ...ETH) creates a bad withdrawal claim for all of the ETH in the bridge. Users would be able ...

(ALL_OF_THE)

🔇 Additional comments (1)
pages/stack/transactions/transaction-finality.mdx (1)

1-9: LGTM! Document metadata and imports are properly structured.

The frontmatter contains all necessary metadata, and the imports are appropriate for the document's needs.


Because the Standard Bridge cannot immediately verify withdrawal claims, it delays the claim by 7 days to allow the OP Stack Fault Proof system to filter out any invalid claims. Challenges only remove bad claims without affecting the Standard Bridge or the OP Stack chain.

TODO: It'd be really fun to have a button that (for the bond cost of 0.08 ETH) creates a bad withdrawal claim for all of the ETH in the bridge. Users would be able to see first hand how their claim gets deleted and nothing else happens.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Remove interactive bad withdrawal claim feature TODO.

While educational, implementing a feature that creates bad withdrawal claims could:

  1. Encourage malicious behavior
  2. Pose security risks
  3. Lead to unnecessary bond costs for users
-TODO: It'd be really fun to have a button that (for the bond cost of 0.08 ETH) creates a bad withdrawal claim for all of the ETH in the bridge. Users would be able to see first hand how their claim gets deleted and nothing else happens.

Consider these safer alternatives:

  1. Create a simulation that doesn't interact with real contracts
  2. Use a testnet environment with limited funds
  3. Provide a video demonstration
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
TODO: It'd be really fun to have a button that (for the bond cost of 0.08 ETH) creates a bad withdrawal claim for all of the ETH in the bridge. Users would be able to see first hand how their claim gets deleted and nothing else happens.
🧰 Tools
🪛 LanguageTool

[style] ~73-~73: Consider removing “of” to be more concise
Context: ...ETH) creates a bad withdrawal claim for all of the ETH in the bridge. Users would be able ...

(ALL_OF_THE)

Copy link
Contributor

@zainbacchus zainbacchus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still todos

@krofax
Copy link
Contributor Author

krofax commented Nov 7, 2024

Still todos

Removed.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Outside diff range and nitpick comments (1)
pages/stack/transactions/transaction-finality.mdx (1)

14-21: Add comma for better readability.

Add a comma after "order" to improve the sentence structure.

-OP Stack chains in the standard configuration are Rollups that use Ethereum's consensus mechanism to order and finalize transactions rather than running a separate consensus protocol.
+OP Stack chains in the standard configuration are Rollups that use Ethereum's consensus mechanism to order, and finalize transactions rather than running a separate consensus protocol.
🧰 Tools
🪛 LanguageTool

[uncategorized] ~20-~20: Possible missing comma found.
Context: ...nsensus mechanism to order and finalize transactions rather than running a separate consensu...

(AI_HYDRA_LEO_MISSING_COMMA)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between 45a3248 and 1186141.

📒 Files selected for processing (1)
  • pages/stack/transactions/transaction-finality.mdx (1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/stack/transactions/transaction-finality.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:
    1. Use sentence case, capitalizing only the first word.
    2. 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.
    3. 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/transactions/transaction-finality.mdx

[uncategorized] ~20-~20: Possible missing comma found.
Context: ...nsensus mechanism to order and finalize transactions rather than running a separate consensu...

(AI_HYDRA_LEO_MISSING_COMMA)


[uncategorized] ~27-~27: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ating that the transaction is in a block but its data has not yet been posted to Eth...

(COMMA_COMPOUND_SENTENCE_2)

🔇 Additional comments (3)
pages/stack/transactions/transaction-finality.mdx (3)

1-13: LGTM! Clear and well-structured introduction.

The frontmatter and introduction effectively set up the document's purpose and scope.


83-85: LGTM! Clear and effective conclusion.

The conclusion effectively summarizes the key points about transaction finality in OP Stack.


75-77: 🛠️ Refactor suggestion

Improve technical accuracy of reorg descriptions.

The timing and technical details need to be more precise.

-*   **Unsafe blocks:** The Sequencer can reorganize these blocks (typically within \~5–10 minutes).
-*   **Safe blocks:** The Sequencer would need to trigger a reorg on Ethereum itself, which is complex and unlikely.
-*   **Finalized blocks:** Once blocks are included in a finalized Ethereum block (typically after \~15–30 minutes)
+*   **Unsafe blocks:** The Sequencer can reorganize these blocks until they are published to Ethereum.
+*   **Safe blocks:** The Sequencer would need to trigger a reorg on Ethereum itself, which requires significant network control.
+*   **Finalized blocks:** Once blocks are included in a finalized Ethereum block (typically after ~12.8 minutes under normal conditions)

Likely invalid or redundant comment.

Comment on lines +57 to +61
A common misconception is that transactions on OP Stack chains take 7 days to finalize. **This is incorrect.** Transactions on OP Stack chains become finalized when their data is included in a finalized Ethereum block, typically around 20–30 minutes after submission. To reorg a finalized OP Stack chain transaction, a reorg of the corresponding Ethereum block would be required.

This misconception often arises due to the OP Stack's Standard Bridge, which includes a 7-day delay on *withdrawals* of ETH and ERC-20 tokens. Withdrawing tokens from an OP Stack chain to Ethereum using the Standard Bridge requires a minimum 7-day wait. This delay affects only withdrawals through the Standard Bridge and does not impact transaction finality on the OP Stack chain.

### Challenges in the Standard Bridge can cause a chain reorg
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Align timing information with earlier sections.

The timing information should be consistent with the earlier sections.

-Transactions on OP Stack chains become finalized when their data is included in a finalized Ethereum block, typically around 20–30 minutes after submission.
+Transactions on OP Stack chains become finalized when their data is included in a finalized Ethereum block, typically after about 12.8 minutes from submission under normal network conditions.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
A common misconception is that transactions on OP Stack chains take 7 days to finalize. **This is incorrect.** Transactions on OP Stack chains become finalized when their data is included in a finalized Ethereum block, typically around 20–30 minutes after submission. To reorg a finalized OP Stack chain transaction, a reorg of the corresponding Ethereum block would be required.
This misconception often arises due to the OP Stack's Standard Bridge, which includes a 7-day delay on *withdrawals* of ETH and ERC-20 tokens. Withdrawing tokens from an OP Stack chain to Ethereum using the Standard Bridge requires a minimum 7-day wait. This delay affects only withdrawals through the Standard Bridge and does not impact transaction finality on the OP Stack chain.
### Challenges in the Standard Bridge can cause a chain reorg
A common misconception is that transactions on OP Stack chains take 7 days to finalize. **This is incorrect.** Transactions on OP Stack chains become finalized when their data is included in a finalized Ethereum block, typically after about 12.8 minutes from submission under normal network conditions. To reorg a finalized OP Stack chain transaction, a reorg of the corresponding Ethereum block would be required.
This misconception often arises due to the OP Stack's Standard Bridge, which includes a 7-day delay on *withdrawals* of ETH and ERC-20 tokens. Withdrawing tokens from an OP Stack chain to Ethereum using the Standard Bridge requires a minimum 7-day wait. This delay affects only withdrawals through the Standard Bridge and does not impact transaction finality on the OP Stack chain.
### Challenges in the Standard Bridge can cause a chain reorg

Comment on lines +22 to +52
## Steps to finality

Transactions on OP Stack chains go through the following process to reach finality:

1. A user submits a transaction to the network, which forwards it to the Sequencer.
2. The Sequencer includes the transaction in a block and distributes it over a public peer-to-peer network. At this point, the transaction is considered **"unsafe"**, a technical term indicating that the transaction is in a block but its data has not yet been posted to Ethereum. This process typically takes only a few seconds.
3. The Sequencer publishes this block's data to Ethereum, either as [blob data](https://www.eip4844.com/) or as calldata attached to a standard Ethereum transaction. Once included in an Ethereum block, the transaction is considered **"safe"**. This step usually takes 5–10 minutes.
4. The Ethereum block containing the Sequencer's transaction is finalized. At this point, the transaction reaches a **"finalized"** state. Ethereum finalization typically takes about 65 Ethereum blocks, or approximately 13 minutes, but may take longer under certain network conditions. Finality depends entirely on [Ethereum's consensus mechanism](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#finality).

```mermaid

sequenceDiagram
participant User
participant Network
participant Sequencer
participant Ethereum

User->>Network: Submit transaction
Network->>Sequencer: Forward transaction
Sequencer->>Sequencer: Include transaction in block
Sequencer->>Network: Distribute block over P2P network
Note right of Sequencer: Transaction status: "unsafe"<br>(block data not yet posted to Ethereum)<br>~a few seconds

Sequencer->>Ethereum: Publish block data (as blob data<br>or calldata)
Note right of Ethereum: Transaction status: "safe"<br>(included in Ethereum block)<br>~5–10 minutes

Ethereum->>Ethereum: Finalize block (~65 blocks or ~13 mins)
Note right of Ethereum: Transaction status: "finalized"<br>~13 minutes (may vary)


```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Standardize timing information.

The timing information should be consistent and precise throughout the section:

-This process typically takes only a few seconds.
+This process typically takes a few seconds from transaction submission.

-This step usually takes 5–10 minutes.
+This step usually takes 5–10 minutes from transaction submission.

-Ethereum finalization typically takes about 65 Ethereum blocks, or approximately 13 minutes
+Ethereum finalization typically takes about 2 epochs (approximately 12.8 minutes from transaction submission) under normal network conditions, but may take longer during adverse conditions
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Steps to finality
Transactions on OP Stack chains go through the following process to reach finality:
1. A user submits a transaction to the network, which forwards it to the Sequencer.
2. The Sequencer includes the transaction in a block and distributes it over a public peer-to-peer network. At this point, the transaction is considered **"unsafe"**, a technical term indicating that the transaction is in a block but its data has not yet been posted to Ethereum. This process typically takes only a few seconds.
3. The Sequencer publishes this block's data to Ethereum, either as [blob data](https://www.eip4844.com/) or as calldata attached to a standard Ethereum transaction. Once included in an Ethereum block, the transaction is considered **"safe"**. This step usually takes 5–10 minutes.
4. The Ethereum block containing the Sequencer's transaction is finalized. At this point, the transaction reaches a **"finalized"** state. Ethereum finalization typically takes about 65 Ethereum blocks, or approximately 13 minutes, but may take longer under certain network conditions. Finality depends entirely on [Ethereum's consensus mechanism](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#finality).
```mermaid
sequenceDiagram
participant User
participant Network
participant Sequencer
participant Ethereum
User->>Network: Submit transaction
Network->>Sequencer: Forward transaction
Sequencer->>Sequencer: Include transaction in block
Sequencer->>Network: Distribute block over P2P network
Note right of Sequencer: Transaction status: "unsafe"<br>(block data not yet posted to Ethereum)<br>~a few seconds
Sequencer->>Ethereum: Publish block data (as blob data<br>or calldata)
Note right of Ethereum: Transaction status: "safe"<br>(included in Ethereum block)<br>~5–10 minutes
Ethereum->>Ethereum: Finalize block (~65 blocks or ~13 mins)
Note right of Ethereum: Transaction status: "finalized"<br>~13 minutes (may vary)
```
## Steps to finality
Transactions on OP Stack chains go through the following process to reach finality:
1. A user submits a transaction to the network, which forwards it to the Sequencer.
2. The Sequencer includes the transaction in a block and distributes it over a public peer-to-peer network. At this point, the transaction is considered **"unsafe"**, a technical term indicating that the transaction is in a block but its data has not yet been posted to Ethereum. This process typically takes a few seconds from transaction submission.
3. The Sequencer publishes this block's data to Ethereum, either as [blob data](https://www.eip4844.com/) or as calldata attached to a standard Ethereum transaction. Once included in an Ethereum block, the transaction is considered **"safe"**. This step usually takes 5–10 minutes from transaction submission.
4. The Ethereum block containing the Sequencer's transaction is finalized. At this point, the transaction reaches a **"finalized"** state. Ethereum finalization typically takes about 2 epochs (approximately 12.8 minutes from transaction submission) under normal network conditions, but may take longer during adverse conditions. Finality depends entirely on [Ethereum's consensus mechanism](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#finality).
```mermaid
sequenceDiagram
participant User
participant Network
participant Sequencer
participant Ethereum
User->>Network: Submit transaction
Network->>Sequencer: Forward transaction
Sequencer->>Sequencer: Include transaction in block
Sequencer->>Network: Distribute block over P2P network
Note right of Sequencer: Transaction status: "unsafe"<br>(block data not yet posted to Ethereum)<br>~a few seconds
Sequencer->>Ethereum: Publish block data (as blob data<br>or calldata)
Note right of Ethereum: Transaction status: "safe"<br>(included in Ethereum block)<br>~5–10 minutes
Ethereum->>Ethereum: Finalize block (~65 blocks or ~13 mins)
Note right of Ethereum: Transaction status: "finalized"<br>~13 minutes (may vary)
```
🧰 Tools
🪛 LanguageTool

[uncategorized] ~27-~27: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ating that the transaction is in a block but its data has not yet been posted to Eth...

(COMMA_COMPOUND_SENTENCE_2)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[DOCS] Explain tx finality, fault proof window, and sequencer policy
6 participants