Skip to content

Specify Distinction between Reorg and Replacement #688

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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Specify Distinction between Reorg and Replacement #688

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 30 additions & 3 deletions specs/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,14 +125,41 @@ verified against the Merkle root.

## Chain Re-Organization

Note: As of the current state of this PR, it is possible for "reorg" and "replacement" to be used as interchangable terms.

[reorg]: glossary.md#chain-re-organization

A re-organization, or re-org for short, is whenever the head of a blockchain (its last block) changes (as dictated by
the [fork choice rule][fork-choice-rule]) to a block that is not a child of the previous head.
Copy link
Contributor Author

@axelKingsley axelKingsley Apr 28, 2025

Choose a reason for hiding this comment

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

I found this line confusing previously because it seemed to indicate the parent<>child relationship of the blockchain gets broken when a reorg occurs, which is not the case. Rather, it's saying that while you might expect some next block to occur, the new block is actually replacing some block-height you've already seen, and so it is not a child of the previous head.

Copy link
Contributor

@ajsutton ajsutton Apr 29, 2025

Choose a reason for hiding this comment

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

I'd probably stick with the original text here. I think the new version is a bit too ambiguous about whether adding a new block to the chain is a re-org (its not but it is an example of a node changing the head block). Although it should be "not a descendant of the previous head" - it's not a reorg to import 2 blocks at once.

Or to look at it another way, a re-org is when the canonical block at particular block number is replaced by a different block.

Copy link
Contributor Author

@axelKingsley axelKingsley Apr 29, 2025

Choose a reason for hiding this comment

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

Or to look at it another way, a re-org is when the canonical block at particular block number is replaced by a different block.

Ah good catch, I indeed left open that natural chain-extension is implicated in my definition. I'll take how you've phrased it, it's simple and captures the definition.

A re-organization, or re-org for short, is whenever a Node on the blockchain changes (as dictated by
the [fork choice rule][fork-choice-rule]) the head block (or multiple blocks) with other blocks.

Reorgs are related to a reselection of branch on a node when there is some form of equivocation. Reorgs may not be seen
by all nodes on the network, if those nodes picked the correct branch to begin with (for example, if they are syncing
well after the reorg occured, only the canonical branch is available).

L1 re-orgs can happen because of network conditions or attacks. L2 re-orgs are a consequence of L1 re-orgs, mediated via
The following are types of reorgs which can be experienced by a node:
Copy link
Contributor Author

@axelKingsley axelKingsley Apr 28, 2025

Choose a reason for hiding this comment

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

These examples may not be comprehensive, and I'm not sure we would want them to be. Opinions?

- Unsafe -> Unsafe Reorg. When the block builder equivocates, a node could accept one unsafe block, and then reject it for
another unsafe block. As implemented today this is not the behavior of Nodes: the Unsafe Chain Consensus is
First-Block-Wins, because the Sequencer is expected *not* to equivocate.
- Unsafe -> Safe Reorg. When the L1 batch data creates a chain which disagrees with the Unsafe Chain currently on the Node,
the Safe Chain always wins.
- L1 Reorg. A reorg on the L1 can occur, which may change the L2 Safe Data which has been posted. This is mediated via
Copy link
Contributor

@ajsutton ajsutton Apr 29, 2025

Choose a reason for hiding this comment

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

The L1 reorg can also change the unsafe chain even if the L1 re-org doesn't affect any submitted batch data. Each L2 block references an L1 block as its origin and that L1 block must be canonical, so if the origin block is re-orged out, the L2 block must also be re-orged out (which may happen if its safe or not and separately to the batch data being reforged).

[L2 chain derivation][derivation].

[replacement]: glossary.md#replacement

A replacement is similar to a reorg in that it changes the historical view of the chain
held by a Node. *Unlike* a reorg, a replacement is handled as part of [L2 chain derivation][derivation].
A replacement is seen on all Nodes on the network, because it is based on
L1 published batch data, which all nodes consume in order to derive.

The following are types of reorgs which can be experienced by a node:
Copy link
Contributor Author

@axelKingsley axelKingsley Apr 28, 2025

Choose a reason for hiding this comment

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

Same here, these examples may not be comprehensive, and I'm not sure we would want them to be. Opinions?

- Derivation Replacement. When a batch contains invalid data, it is immediately replaced
by a deposit-only block. This is atomic: the replacement can occur as soon as the batch content is considered.
- Interop Replacement. When L1 data reveals that some interop dependency is invalid,
the block with the invalid message is replaced by a deposit-only block. The block which is replaced,
and all blocks which come from it, are no longer part of the canonical chain, even though they may appear
locally valid for several L1 blocks.
Comment on lines +158 to +161
Copy link
Contributor

@ajsutton ajsutton Apr 29, 2025

Choose a reason for hiding this comment

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

Given that interop replacement happens after a block is first imported it will cause a re-org (interop replacements are a subset of re-orgs). Derivation replacements just change what block is created from a batch - that may cause a re-org because the replacement doesn't match up with the unsafe chain but doesn't have to.

Copy link
Contributor Author

@axelKingsley axelKingsley Apr 29, 2025

Choose a reason for hiding this comment

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

Hm, that's an interesting line to draw. I agree that an interop replacement fits the description of "one block has been replaced with another", but the distinction I was going for was that interop replacements are not "re-orgs" because they are experienced as part of derivation, and so all nodes perform this replacement.

I think I'm under-defining "reorg" here, and I'm not sure if you'd agree with what I'm thinking: The traditional thing people think of when they hear "reorg" is an equivocation, where nodes who selected the wrong branch first see a correction, where nodes who happened to see the right branch first don't see a reorg at all. That's why I specify that not all nodes may see a reorg, while all nodes do see a replacement.

Seems like you are suggesting that Interop Replacement is a replacement which can cause reorg, because the replacement still changes one block for another, even though it is triggered by the derivation process.

I can reframe things more in that direction

Copy link
Contributor

@ajsutton ajsutton Apr 30, 2025

Choose a reason for hiding this comment

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

I wouldn't say that a re-org is always because of equivocation - L1 has a distributed validator set so often creates alternate forks just because of the delay in reaching consensus and delays propagating blocks etc. And because an L1 re-org can cause an L2 re-org you can get re-orgs without equivocation there too (including the sequencer legitimately creating to different blocks with the same number because they need to refer to different L1 origins).

But yes I would agree with the idea that re-org is something where a node's view changes and not all nodes will necessarily see that. Interop is an interesting case because the validation is done somewhat lazily so it's possible that different nodes will determine they need to perform the replacement at different times and thus see the resulting re-org differently (ie they may have received and follow more local-safe or unsafe blocks than other nodes).

I don't know - I'm starting to get fairly confused by trying to draw this distinction to be honest...

Copy link
Contributor Author

@axelKingsley axelKingsley May 1, 2025

Choose a reason for hiding this comment

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

validation is done somewhat lazily so it's possible that different nodes will determine they need to perform the replacement at different times and thus see the resulting re-org differently (ie they may have received and follow more local-safe or unsafe blocks than other nodes).

It is true that nodes could have received a different quantity of unsafe blocks, but it is not possible for them to receive more or fewer safe blocks - derivation is incremental against the L1, and for any given L1 there is a single definition for local and cross safe. If there is insufficient data, the cross lags the local, but by a deterministic amount. The only way to see the replacement without seeing the same number of batches as your peers is if you intentionally ignore the L1 data, which no implementation or design does (it's also not clear how a derivation pipeline would achieve this, since an interop replacement contains reference to the block which is being replaced. That block must be arrived at, and may need to be waited-at for some number of L1 blocks).


## Predeployed Contract ("Predeploy")

[predeploy]: glossary.md#predeployed-contract-predeploy
Expand Down