Skip to content
This repository was archived by the owner on Apr 6, 2026. It is now read-only.

Update bootstrap command docs in op-deployer docs #1368

Merged
krofax merged 3 commits into from
Feb 17, 2025
Merged

Update bootstrap command docs in op-deployer docs #1368

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
598a38e
updated bootstrap command docs
krofax Feb 14, 2025
1dc12fb
update the callout
krofax Feb 14, 2025
0b8736c
fix merge conflict
krofax Feb 17, 2025
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
24 changes: 16 additions & 8 deletions pages/operators/chain-operators/tools/op-deployer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,19 +129,27 @@ op-deployer inspect l2-semvers --workdir .deployer <l2-chain-id> # outputs the s

## Bootstrap usage

You can also use `op-deployer` to deploy the contracts needed to run the `init`... `apply` flow on new chains. This process, called 'bootstrapping,' is useful when you want to use `op-deployer` with L3s, new testnets, or other custom settlement chains.
The bootstrap commands are specialized tools primarily used for initializing a new superchain on an L1 network that hasn't previously hosted one.

### OPCM bootstrap

To deploy OPCM to a new chain, run the following command:
### Available commands

```bash
op-deployer bootstrap opcm \
--l1-rpc-url <mainnet-rpc-url> \
--private-key <deployer-private-key> \
--artifacts-locator tag://op-contracts/v1.6.0
op-deployer bootstrap superchain
op-deployer bootstrap implementations
op-deployer bootstrap proxy
```

### Use cases

The bootstrap commands are specifically designed for scenarios such as:
* Setting up a superchain on a new EVM-compatible L1.
* Initializing superchain contracts on a new Ethereum testnet (e.g., an alternative to Sepolia).
* Creating the foundational infrastructure for a brand new superchain deployment.

<Callout type="info">
For standard chain deployments, use the [op-deployer `apply`](/operators/chain-operators/tools/op-deployer#apply) command.
</Callout>

## Next steps

* For more details, check out the tool and documentation in the [op-deployer repository](https://github.com/ethereum-optimism/optimism/tree/develop/op-deployer/cmd/op-deployer).
Expand Down
2 changes: 2 additions & 0 deletions pages/stack/interop.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,6 @@ Documentation covering Cross Chain Message, Explainer, Message Passing, Op Super
<Card title="Tutorials" href="/stack/interop/tutorials" icon={<img src="/img/icons/shapes.svg" />} />

<Card title="Safe interoperability measures" href="/stack/interop/interop-security" icon={<img src="/img/icons/shapes.svg" />} />

<Card title="Interop reorg awareness" href="/stack/interop/reorg" />
</Cards>
105 changes: 50 additions & 55 deletions pages/stack/interop/reorg.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,45 +13,43 @@ import { InteropCallout } from '@/components/WipCallout'

# Interop reorg awareness

[A chain reorganization, or “reorg”,](https://www.alchemy.com/overviews/what-is-a-reorg#what-happens-to-reorgs-after-the-merge) happens when validators disagree on the most accurate version of the blockchain.
If not handled correctly, reorgs in a cross-chain context could result in a [double-spend problem](https://en.wikipedia.org/wiki/Double-spending).
[A chain reorganization, or "reorg",](https://www.alchemy.com/overviews/what-is-a-reorg#what-happens-to-reorgs-after-the-merge) happens when validators disagree on the most accurate version of the blockchain.
If not handled correctly, reorgs in a cross-chain context could result in a [double-spend problem](https://en.wikipedia.org/wiki/Double-spending).
The most frequent solution to mitigate the double-spend problem is to wait for Ethereum finality; however, that solution results in high latency cross-chain communication and a poor user experience.

<details>

<summary>What is double-spending?</summary>

```mermaid

flowchart LR
subgraph init ["Initiating transaction (source chain)"]
burn(tokens burned)
burn-->send(send)
end
subgraph exec ["Executing transaction (destination chain)"]
send==initiating message==>receive(receive)
receive-->mint(tokens minted)
end
```

In a normal asset transfer tokens are burned on the source chain first, then a message is sent to the destination chain.
When that message is received, the tokens are minted on the destination chain, where the user can now use those tokens.

```mermaid

flowchart LR
subgraph init ["Not really the source chain"]
err((error))
end
subgraph exec ["Executing transaction (destination chain)"]
err==initiating message==>receive(receive)
receive-->mint(tokens minted)
end
```

A double-spend problem occurs when the destination chain receives a valid initiating message, but due to issues on the source chain, such as a reorg, that initiating transaction is no longer valid.
When that happens, the tokens are still on the source chain, but they are also on the destination chain.

<summary>What is double-spending?</summary>

```mermaid

flowchart LR
subgraph init ["Initiating transaction (source chain)"]
burn(tokens burned)
burn-->send(send)
end
subgraph exec ["Executing transaction (destination chain)"]
send==initiating message==>receive(receive)
receive-->mint(tokens minted)
end
```

In a normal asset transfer tokens are burned on the source chain first, then a message is sent to the destination chain.
When that message is received, the tokens are minted on the destination chain, where the user can now use those tokens.

```mermaid

flowchart LR
subgraph init ["Not really the source chain"]
err((error))
end
subgraph exec ["Executing transaction (destination chain)"]
err==initiating message==>receive(receive)
receive-->mint(tokens minted)
end
```

A double-spend problem occurs when the destination chain receives a valid initiating message, but due to issues on the source chain, such as a reorg, that initiating transaction is no longer valid.
When that happens, the tokens are still on the source chain, but they are also on the destination chain.
</details>

Most solutions to mitigate the double-spend problem rely on [L1 finality](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#finality). However, that solution results in high latency and poor user experience.
Expand Down Expand Up @@ -81,13 +79,13 @@ graph LR
class A101,A102,A103,B302,B303 unsafe
```

In the diagram above, solid arrows are the derivation of a block from the previous block in the chain.
In the diagram above, solid arrows are the derivation of a block from the previous block in the chain.
Dotted arrows go from the block with the initiating message (the source) to the block with the executing message (the destination).
Blocks can either be finalized (grey), cross-safe (green), or unsafe (red).
Blockchain A has only written block A<sub>100</sub> to the blockchain.
Blockchain A has only written block A<sub>100</sub> to the blockchain.
As a result, block A<sub>101</sub> is unsafe, and so are all the blocks that depend on it, directly (A<sub>102</sub> and B<sub>302</sub>) or indirectly (A<sub>103</sub> and B<sub>303</sub>).
Blocks B<sub>302</sub> and B<sub>303</sub> may be *local-safe* (if they are written to L1), but they cannot be *cross-safe* because they depend on a block that isn't.
If all goes well, eventually A<sub>101</sub> will be written to L1, turn safe, and then the blocks that depend on it can become safe as well.
Blocks B<sub>302</sub> and B<sub>303</sub> may be *local-safe* (if they are written to L1), but they cannot be *cross-safe* because they depend on a block that isn't.
If all goes well, eventually A<sub>101</sub> will be written to L1, turn safe, and then the blocks that depend on it can become safe as well.

The message between A<sub>101</sub> and B<sub>302</sub> can be an asset moving across the bridge.
In that case, the initiating message (A<sub>101</sub>) burns `n` tokens on the source chain (A), and the executing message (B<sub>302</sub>) mints `n` tokens on the destination chain (B).
Expand All @@ -104,11 +102,10 @@ So L1 reorgs are basically invisible to L2.

Sequencers inform the rest of the Superchain about a new block in two ways:

- The gossip protocol, which is typically used as soon as the block is created.
The problem is that the gossip protocol does not create a commitment.
- Posting to L1, which typically happens a few minutes after the block is created.
The reason is cost, it is a lot cheaper if compression and L1 posting are done in large batches, rather than for each individual block.

* The gossip protocol, which is typically used as soon as the block is created.
The problem is that the gossip protocol does not create a commitment.
* Posting to L1, which typically happens a few minutes after the block is created.
The reason is cost, it is a lot cheaper if compression and L1 posting are done in large batches, rather than for each individual block.

Equivocation happens when a sequencer publishes a block using the gossip protocol that is different from the one that eventually gets written to L1.
In this case, the block that is written to L1 (let's call it A'<sub>101</sub>) is the valid one, and that causes every dependent block to be recalculated.
Expand Down Expand Up @@ -154,15 +151,13 @@ So the change from A<sub>101</sub> to A'<sub>101</sub> cannot invalidate any exi
If a block is invalid, even if it is posted on L1, the canonical chain replaces it with a block that only includes the deposit transactions, those transactions posted to L1.

<details>
<summary>What makes a block invalid?</summary>

<summary>What makes a block invalid?</summary>

There are several potential reasons:

- The block posted to L1 includes incorrect information, for example because it relied on a node on a different blockchain for interop and that node reported incorrect information.
- The block was never posted.
After a timeout of twelve hours all the verifiers will assume that the block that should have been posted is a deposit-only block.
There are several potential reasons:

* The block posted to L1 includes incorrect information, for example because it relied on a node on a different blockchain for interop and that node reported incorrect information.
* The block was never posted.
After a timeout of twelve hours all the verifiers will assume that the block that should have been posted is a deposit-only block.
</details>

This is functionally equivalent to equivocation, and dealt with the same way, so it can change unsafe blocks but only those blocks.
Expand All @@ -177,6 +172,6 @@ At worst, some unsafe blocks need to be recalculated (if one fork is chosen over

## Next steps

- Build a [revolutionary app](/app-developers/get-started) that uses multiple blockchains within the Superchain.
- Deploy a [SuperchainERC20](./tutorials/deploy-superchain-erc20) to the Superchain.
- View more [interop tutorials](./tutorials).
* Build a [revolutionary app](/app-developers/get-started) that uses multiple blockchains within the Superchain.
* Deploy a [SuperchainERC20](./tutorials/deploy-superchain-erc20) to the Superchain.
* View more [interop tutorials](./tutorials).
Loading