From 598a38e89b9a6f5254f62357a526caaa8652fa20 Mon Sep 17 00:00:00 2001 From: krofax Date: Fri, 14 Feb 2025 17:57:46 +0100 Subject: [PATCH 1/2] updated bootstrap command docs --- .../chain-operators/tools/op-deployer.mdx | 25 +++-- pages/stack/interop.mdx | 2 + pages/stack/interop/reorg.mdx | 105 +++++++++--------- .../interop/tutorials/message-passing.mdx | 95 +++++++++------- words.txt | 1 + 5 files changed, 122 insertions(+), 106 deletions(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index c611d27a6..b4c108236 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -129,19 +129,28 @@ op-deployer inspect l2-semvers --workdir .deployer # 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 \ - --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. + + + For standard deployments and chain operations, use the [op-deployer `apply`](/operators/chain-operators/tools/op-deployer#apply) command. + The bootstrap commands are specialized tools that will rarely be needed by most users. + + ## 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). diff --git a/pages/stack/interop.mdx b/pages/stack/interop.mdx index 1e131f94f..4b5c0abee 100644 --- a/pages/stack/interop.mdx +++ b/pages/stack/interop.mdx @@ -34,4 +34,6 @@ Documentation covering Cross Chain Message, Explainer, Message Passing, Op Super } /> } /> + + diff --git a/pages/stack/interop/reorg.mdx b/pages/stack/interop/reorg.mdx index 2472da76d..caff773f2 100644 --- a/pages/stack/interop/reorg.mdx +++ b/pages/stack/interop/reorg.mdx @@ -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.
- -What is double-spending? - -```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. - + What is double-spending? + + ```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.
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. @@ -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 A100 to the blockchain. +Blockchain A has only written block A100 to the blockchain. As a result, block A101 is unsafe, and so are all the blocks that depend on it, directly (A102 and B302) or indirectly (A103 and B303). -Blocks B302 and B303 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 A101 will be written to L1, turn safe, and then the blocks that depend on it can become safe as well. +Blocks B302 and B303 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 A101 will be written to L1, turn safe, and then the blocks that depend on it can become safe as well. The message between A101 and B302 can be an asset moving across the bridge. In that case, the initiating message (A101) burns `n` tokens on the source chain (A), and the executing message (B302) mints `n` tokens on the destination chain (B). @@ -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'101) is the valid one, and that causes every dependent block to be recalculated. @@ -154,15 +151,13 @@ So the change from A101 to A'101 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.
+ What makes a block invalid? -What makes a block invalid? - -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.
This is functionally equivalent to equivocation, and dealt with the same way, so it can change unsafe blocks but only those blocks. @@ -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). \ No newline at end of file +* 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). diff --git a/pages/stack/interop/tutorials/message-passing.mdx b/pages/stack/interop/tutorials/message-passing.mdx index 9ffbdd62e..00a63a96a 100644 --- a/pages/stack/interop/tutorials/message-passing.mdx +++ b/pages/stack/interop/tutorials/message-passing.mdx @@ -93,10 +93,9 @@ For development purposes, we'll first use autorelay mode to handle message execu ### Setting up test networks - - + If you attempt to run these steps with the [devnet](../tools/devnet), you *must* Send the executing message yourself, as explained [here](#implement-manual-message-relaying). - + 1. In the directory where Supersim is installed, start it with autorelay. @@ -107,7 +106,7 @@ For development purposes, we'll first use autorelay mode to handle message execu Supersim creates three `anvil` blockchains: | Role | ChainID | RPC URL | - | -------- | ------: | --------------------------------------------- | + | -------- | ------: | ---------------------------------------------- | | L1 | 900 | [http://127.0.0.1:8545](http://127.0.0.1:8545) | | OPChainA | 901 | [http://127.0.0.1:9545](http://127.0.0.1:9545) | | OPChainB | 902 | [http://127.0.0.1:9546](http://127.0.0.1:9546) | @@ -143,11 +142,12 @@ For development purposes, we'll first use autorelay mode to handle message execu cd onchain-code forge init ``` + 2. In `src/Greeter.sol` put this file. This is a variation on [Hardhat's Greeter contract](https://github.com/matter-labs/hardhat-zksync/blob/main/examples/upgradable-example/contracts/Greeter.sol). - ```solidity file=/public/tutorials/Greeter.sol#L1-L20 hash=b3c5550bcc2cc4272125388ef23a67e7 - ``` + ```solidity file=/public/tutorials/Greeter.sol#L1-L20 hash=b3c5550bcc2cc4272125388ef23a67e7 + ``` 3. Deploy the `Greeter` contract to Chain B and store the resulting contract address in the `GREETER_B_ADDR` environment variable. @@ -446,8 +446,8 @@ In production we will not have this, we need to create our own executing message 2. Create or replace `src/app.mts` with this code. - ```typescript file=/public/tutorials/app.mts#L1-L51 hash=8f6f776884b8e37ae613f7aea8cd6a3b - ``` + ```typescript file=/public/tutorials/app.mts#L1-L51 hash=8f6f776884b8e37ae613f7aea8cd6a3b + ``` 3. Run the program, see that a greeting from chain A is relayed to chain B. @@ -495,49 +495,58 @@ In production we will not have this, we need to create our own executing message 1. Replace `src/app.mts` with: - ```typescript file=/public/tutorials/app_v2.mts hash=a7b0f60aa6f1e48fc9994178ed3d5498 - ``` + ```typescript file=/public/tutorials/app_v2.mts hash=a7b0f60aa6f1e48fc9994178ed3d5498 + ```
- Explanation + Explanation + + 1. **Import Required Libraries** + + * Imports functions from `viem` for wallet creation, HTTP transport, and contract interactions. - 1. **Import Required Libraries** + * Imports `@eth-optimism/viem` utilities for handling OP-Stack-specific actions and interoperability. - * Imports functions from `viem` for wallet creation, HTTP transport, and contract interactions. - * Imports `@eth-optimism/viem` utilities for handling OP-Stack-specific actions and interoperability. - * Loads ABI definitions from `Greeter.json` and `GreetingSender.json` for contract interactions. + * Loads ABI definitions from `Greeter.json` and `GreetingSender.json` for contract interactions. - 2. **Initialize Wallet Clients** + 2. **Initialize Wallet Clients** - * Uses `privateKeyToAccount` to generate an account from an environment variable. - * Creates `walletA` for chain `supersimL2A` and `walletB` for chain `supersimL2B`, extending them with Viem's public and OP-Stack-specific actions. + * Uses `privateKeyToAccount` to generate an account from an environment variable. - 3. **Get Contract Instances** + * Creates `walletA` for chain `supersimL2A` and `walletB` for chain `supersimL2B`, extending them with Viem's public and OP-Stack-specific actions. - * Retrieves contract instances for `greeter` on `walletB` and `greetingSender` on `walletA` using `getContract`. - * The addresses are taken from environment variables, and the clients are set to the respective wallets. + 3. **Get Contract Instances** - 4. **Direct Greeting on Chain B** + * Retrieves contract instances for `greeter` on `walletB` and `greetingSender` on `walletA` using `getContract`. - * Calls `setGreeting` on `greeter` to store a greeting directly on chain B. - * Waits for the transaction to be confirmed using `waitForTransactionReceipt`. - * Reads and logs the greeting stored on chain B. + * The addresses are taken from environment variables, and the clients are set to the respective wallets. - 5. **Cross-Chain Greeting via Chain A** + 4. **Direct Greeting on Chain B** - * Calls `setGreeting` on `greetingSender` to send a greeting through chain A. - * Waits for the transaction receipt on chain A. + * Calls `setGreeting` on `greeter` to store a greeting directly on chain B. - 6. **Retrieve and Relay the Cross-Chain Message** + * Waits for the transaction to be confirmed using `waitForTransactionReceipt`. - * Extracts the message from the transaction receipt using `createInteropSentL2ToL2Messages`. - * Relays the message to chain B using `walletB.interop.relayMessage`. - * Waits for confirmation of the relay transaction. + * Reads and logs the greeting stored on chain B. - 7. **Verify the Updated Greeting on Chain B** + 5. **Cross-Chain Greeting via Chain A** - * Reads the greeting from `greeter` after the relay process. - * Logs the updated greeting, showing that it was successfully relayed from chain A to chain B. + * Calls `setGreeting` on `greetingSender` to send a greeting through chain A. + + * Waits for the transaction receipt on chain A. + + 6. **Retrieve and Relay the Cross-Chain Message** + + * Extracts the message from the transaction receipt using `createInteropSentL2ToL2Messages`. + + * Relays the message to chain B using `walletB.interop.relayMessage`. + + * Waits for confirmation of the relay transaction. + + 7. **Verify the Updated Greeting on Chain B** + + * Reads the greeting from `greeter` after the relay process. + * Logs the updated greeting, showing that it was successfully relayed from chain A to chain B.
2. Rerun the JavaScript program, and see that the message is relayed. @@ -552,7 +561,7 @@ In production we will not have this, we need to create our own executing message You can relay messages in exactly the same way you'd do it on Supersim. | Contract | Network | Address | - | --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | ---------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Greeter` | [Devnet 1](../tools/devnet#interop-devnet-1) | [`0x1A183FCf61053B7dcd2322BbE766f7E1946d3718`](https://sid.testnet.routescan.io/address/0x1A183FCf61053B7dcd2322BbE766f7E1946d3718) | | `GreetingSender` | [Devnet 0](../tools/devnet#interop-devnet-1) | [`0x9De9f84a4EB3616B44CF1d68cD1A9098Df6cB25f`](https://sid.testnet.routescan.io/address/0x9De9f84a4EB3616B44CF1d68cD1A9098Df6cB25f/contract/420120000/readContract?chainid=420120000) | @@ -561,7 +570,7 @@ In production we will not have this, we need to create our own executing message 1. In `src/app.mts`, replace these lines to update the chains and contract addresses. | Line number | New content | - | ----------: | ------------------------------------------------------------------------- | + | ----------: | -------------------------------------------------------------------------- | | 9 | `import { interopAlpha0, interopAlpha1 } from '@eth-optimism/viem/chains'` | | 23 | ` chain: interopAlpha0,` | | 31 | ` chain: interopAlpha1,` | @@ -574,14 +583,14 @@ In production we will not have this, we need to create our own executing message export PRIV_KEY=0x ``` - 3. Send ETH to the two L2 blockchains. + 3. Send ETH to the two L2 blockchains. - ```sh - cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIV_KEY --value 0.001ether 0x7385d89d38ab79984e7c84fab9ce5e6f4815468a - cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIV_KEY --value 0.001ether 0x7385d89d38ab79984e7c84fab9ce5e6f4815468a - ``` + ```sh + cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIV_KEY --value 0.001ether 0x7385d89d38ab79984e7c84fab9ce5e6f4815468a + cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIV_KEY --value 0.001ether 0x7385d89d38ab79984e7c84fab9ce5e6f4815468a + ``` - Wait a few minutes until you can see the ETH [on your explorer](https://sid.testnet.routescan.io/). + Wait a few minutes until you can see the ETH [on your explorer](https://sid.testnet.routescan.io/). 3. Rerun the test. diff --git a/words.txt b/words.txt index 76ee91283..f4402123e 100644 --- a/words.txt +++ b/words.txt @@ -338,6 +338,7 @@ Reown Reown's replayability replayor +reposts REQUIREDBLOCKS requiredblocks rollouts From 1dc12fbcb182554f850f617bbc7d6500e072430b Mon Sep 17 00:00:00 2001 From: krofax Date: Fri, 14 Feb 2025 18:13:17 +0100 Subject: [PATCH 2/2] update the callout --- pages/operators/chain-operators/tools/op-deployer.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index b4c108236..a4f89714f 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -147,8 +147,7 @@ The bootstrap commands are specifically designed for scenarios such as: * Creating the foundational infrastructure for a brand new superchain deployment. - For standard deployments and chain operations, use the [op-deployer `apply`](/operators/chain-operators/tools/op-deployer#apply) command. - The bootstrap commands are specialized tools that will rarely be needed by most users. + For standard chain deployments, use the [op-deployer `apply`](/operators/chain-operators/tools/op-deployer#apply) command. ## Next steps