Skip to content

Conversation

@axelKingsley
Copy link
Contributor

Very WIP, just starting by throwing the definitions I have out there with the examples I know.

Looking for any early feedback on the statements themselves, where I've located them, etc.

Haven't cross-linked all appropriate spec items yet (like unsafe chain selection rules), will do once people like the words.

@axelKingsley axelKingsley requested review from a team as code owners April 28, 2025 21:46
@axelKingsley axelKingsley force-pushed the glossary-reorg-replacement branch from f94a0ce to 215bcd5 Compare April 28, 2025 21:51
[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

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

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

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.

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

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?

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

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?

Copy link
Contributor

@ajsutton ajsutton left a comment

Choose a reason for hiding this comment

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

It think it's very confusing to have derivation replacement and interop replacement. When interop replaces a block it will always be a reorg (in the local-safe and unsafe parts of the chain). When derivation inserts a deposit-only block because a batch produced an invalid block, that's a replacement which may or may not trigger a reorg depending on whether the canonical chain was built on the original block.

I do think there's a useful terminology difference between replacement and reorg but I'm not sure this has nailed it exactly.

[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

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.

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

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).

Comment on lines +158 to +161
- 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.
Copy link
Contributor

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

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

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

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).

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.

3 participants