Merge pull request #138 from ethereum-optimism/09-11-docs_create_docs…

…_site docs: create docs site
ethereum-optimism · Sep 11, 2024 · 9d26671 · 9d26671
2 parents 7ec4e42 + d3ad20b
commit 9d26671
Show file tree

Hide file tree

Showing 20 changed files with 652 additions and 1 deletion.
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,32 @@
+name: Deploy docs
+on:
+  push:
+    branches:
+      - main
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      deployments: write
+    name: Publish to GitHub Pages
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+      - name: Install Rust stable toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Setup mdbook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "latest"
+      - name: Build book
+        run: mdbook build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ As we move towards a multi-chain future, the ability to develop and test applica
 
 `supersim` requires `anvil` to be installed.
 
-Follow the guide [here](https://book.getfoundry.sh/getting-started/installation) to install the Foundry toolchain.
+Follow the guide [here](https://book.getfoundry.sh/getting-started/installation) to install the Foundry toolchain, which includes `anvil`.
 
 ### 2. Install `supersim`
 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+book/
diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,6 @@
+[book]
+authors = ["optimism-collective"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Supersim"
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -0,0 +1,32 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+# Getting Started
+
+- [Installation](./getting-started/installation.md)
+- [First steps](./getting-started/first-steps.md)
+
+# CLI Reference
+
+- [supersim](./reference/supersim.md)
+- [supersim fork](./reference/supersim-fork.md)
+
+# Chain Environment
+
+- [Included contracts](./chain-environment/contracts/README.md)
+- [Network details & contract addresses](./chain-environment/network-details/README.md)
+  - [OPChainA](./chain-environment/network-details/op-chain-a.md)
+  - [OPChainB](./chain-environment/network-details/op-chain-b.md)
+
+# Guides
+
+- [Sending deposit transactions](./guides/deposit-transactions.md)
+- [Interoperability](./guides/interop/README.md)
+  - [Fetching identifiers for interop messages](./guides/interop/interop-identifiers.md)
+  - [Calling contract on other chain](./guides/interop/calling-destination-contract.md)
+  - [Bridging SuperchainWETH](./guides/interop/bridging-superchainweth.md)
+
+# Examples
+
+- [Cross-chain tic-tac-toe](./examples/cross-chain-tictactoe.md)
diff --git a/docs/src/chain-environment/contracts/README.md b/docs/src/chain-environment/contracts/README.md
@@ -0,0 +1,44 @@
+<!-- omit in toc -->
+# Included contracts
+
+The chain environment includes contracts already deployed to help replicate the Superchain environment. You can see an example of contract addresses for a L2 system [here](/docs/src/chain-environment/network-details/op-chain-a.md).
+
+- [OP Stack system contracts (L1)](#op-stack-system-contracts-l1)
+- [OP Stack L2 contracts (L2)](#op-stack-l2-contracts-l2)
+- [Periphery contracts (L2)](#periphery-contracts-l2)
+  - [L2NativeSuperchainERC20](#l2nativesuperchainerc20)
+    - [Minting new tokens](#minting-new-tokens)
+
+
+## OP Stack system contracts (L1)
+
+These are the L1 contracts that are required for a rollup as part of the OP Stack protocol. Examples are the [OptimismPortal](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal.sol), [L1StandardBridge](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1StandardBridge.sol), and [L1CrossDomainMessenger](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol).
+
+View examples of these contracts here the official [OP docs](https://docs.optimism.io/chain/addresses#ethereum-l1) or the source code [here in the Optimism monorepo](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/src/L1)
+
+## OP Stack L2 contracts (L2)
+
+The OP Stack system contracts on the L2 are included at the standard addresses by default.
+
+- [Standard OP Stack predeploys (L2)](https://specs.optimism.io/protocol/predeploys.html)
+- [Interoperability predeploys (*experimental*) (L2)](https://specs.optimism.io/interop/predeploys.html)
+- [OP Stack preinstalls (L2)](https://specs.optimism.io/protocol/preinstalls.html)
+
+
+## Periphery contracts (L2)
+
+L2 chains running on `supersim` also includes some useful contracts for testing purposes that are not part of the OP Stack by default.
+
+### L2NativeSuperchainERC20
+
+A simple ERC20 that adheres to the SuperchainERC20 standard. It includes permissionless minting for easy testing.
+
+Source: [L2NativeSuperchainERC20.sol](/contracts/src/L2NativeSuperchainERC20.sol)
+
+Deployed address: `0x61a6eF395d217eD7C79e1B84880167a417796172`
+
+#### Minting new tokens
+
+```bash
+cast send 0x61a6eF395d217eD7C79e1B84880167a417796172 "mint(address _to, uint256 _amount)" $RECIPIENT_ADDRESS 1ether  --rpc-url $L2_RPC_URL
+```
diff --git a/docs/src/chain-environment/network-details/README.md b/docs/src/chain-environment/network-details/README.md
@@ -0,0 +1,8 @@
+# Network details
+
+By default, two OP Stack systems will be spun up in vanilla mode
+
+- OPChainA (chainID 901)
+- OPChainB (chainID 902)
+
+Both "roll up" into a single L1 chain (chainID 900).
diff --git a/docs/src/chain-environment/network-details/op-chain-a.md b/docs/src/chain-environment/network-details/op-chain-a.md
@@ -0,0 +1,84 @@
+<!-- omit in toc -->
+# OPChainA
+
+- [Network details](#network-details)
+- [Contract addresses](#contract-addresses)
+  - [L1 contracts](#l1-contracts)
+  - [L2 contracts](#l2-contracts)
+
+## Network details
+
+| **Parameter** | **Value**             |
+|---------------|-----------------------|
+| **Name**      | OPChainA              |
+| **Chain ID**  | 901                   |
+| **RPC URL**   | <http://127.0.0.1:9545> |
+
+## Contract addresses
+
+### L1 contracts
+
+```json
+{
+  "AddressManager": "0x78d21C9820A9135215202A9a8D6521483D4b75cD",
+  "AnchorStateRegistry": "0x21799f09394c50220CCD95E7dAc1cdD774FC871a",
+  "AnchorStateRegistryProxy": "0xa6F40d5770b3509aB40B2effa5cb544D29743ec7",
+  "DelayedWETH": "0x49BBFf1629824A1e7993Ab5c17AFa45D24AB28c9",
+  "DelayedWETHProxy": "0x309DA6B9a8fE16afD7D067528d358E55314bEa6b",
+  "DisputeGameFactory": "0x20B168142354Cee65a32f6D8cf3033E592299765",
+  "DisputeGameFactoryProxy": "0x444689B81D485bc58AB81aC02A95a937fAa152D7",
+  "L1CrossDomainMessenger": "0x094e6508ba9d9bf1ce421fff3dE06aE56e67901b",
+  "L1CrossDomainMessengerProxy": "0xe5bda89cd85cE0DfB80E053281cA070D65B738e6",
+  "L1ERC721Bridge": "0x5C4F5e749A61a9503c4AAE8a9393e89609a0e804",
+  "L1ERC721BridgeProxy": "0x018dC24a6617c47cAa00C3fA25097214B2D4F447",
+  "L1StandardBridge": "0xb7900B27Be8f0E0fF65d1C3A4671e1220437dd2b",
+  "L1StandardBridgeProxy": "0xa01ae68902e205B420FD164435F299E07b0C778b",
+  "L2OutputOracle": "0x19652082F846171168Daf378C4fD3ee85a0D4A60",
+  "L2OutputOracleProxy": "0x6cE0530E823e23be85D8e151FB023605eB4F6d43",
+  "Mips": "0xB3A0348310a0ff78E5FbDB7f14BB7d3e02d40773",
+  "OptimismMintableERC20Factory": "0x39Aea2Dd53f2d01c15877aCc2791af6BDD7aD567",
+  "OptimismMintableERC20FactoryProxy": "0x15c855966C196Be3a8ca747E8A8Bf40928d4741f",
+  "OptimismPortal": "0xb7461Fb347f68f9717e6fD12C8407dEcee063bdc",
+  "OptimismPortal2": "0xfcbb237388CaF5b08175C9927a37aB6450acd535",
+  "OptimismPortalProxy": "0xF5fe61a258CeBb54CCe428F76cdeD04Cbc12F53d",
+  "PreimageOracle": "0x3bd7E801E51d48c5d94Ea68e8B801DFFC275De75",
+  "ProtocolVersions": "0xfbfD64a6C0257F613feFCe050Aa30ecC3E3d7C3F",
+  "ProtocolVersionsProxy": "0x6dA4f6489039d9f4F3144954DDF5bb2F4986e90b",
+  "ProxyAdmin": "0xe32a4D31ffD5596542DAc8239a1DE3Fff9d63475",
+  "SafeProxyFactory": "0x4a05c09875DE2DD5B81Bc01dd46eD4699b181bfA",
+  "SafeSingleton": "0x99A395CE6d6b37CaaCBad64fB42d556b6CA73a48",
+  "SuperchainConfig": "0x068E44eB31e111028c41598E4535be7468674D0A",
+  "SuperchainConfigProxy": "0x7E6c6ebCF109fa23277b86bdA39738035C21BB86",
+  "SystemConfig": "0x6167B477F8d9138aa509f54b2800443857e28c0f",
+  "SystemConfigProxy": "0xf32919Ed2490b56EaD65E72749894aE4C9523320",
+  "SystemOwnerSafe": "0xc052b7316C87390E555aF97D42bCd5FB6d5eEFDa"
+}
+```
+
+### L2 contracts
+
+```json
+{
+  // OP Stack predeploys
+  "L2ToL1MessagePasser": "0x4200000000000000000000000000000000000016",
+  "L2CrossDomainMessenger": "0x4200000000000000000000000000000000000007",
+  "L2StandardBridge": "0x4200000000000000000000000000000000000010",
+  "L2ERC721Bridge": "0x4200000000000000000000000000000000000014",
+  "SequencerFeeVault": "0x4200000000000000000000000000000000000011",
+  "OptimismMintableERC20Factory": "0x4200000000000000000000000000000000000012",
+  "OptimismMintableERC721Factory": "0x4200000000000000000000000000000000000017",
+  "L1BlockInterop": "0x4200000000000000000000000000000000000015",
+  "GasPriceOracle": "0x420000000000000000000000000000000000000F",
+  "ProxyAdmin": "0x4200000000000000000000000000000000000018",
+  "BaseFeeVault": "0x4200000000000000000000000000000000000019",
+  "L1FeeVault": "0x420000000000000000000000000000000000001A",
+  "GovernanceToken": "0x4200000000000000000000000000000000000042",
+  "SchemaRegistry": "0x4200000000000000000000000000000000000020",
+  "EAS": "0x4200000000000000000000000000000000000021",
+  "CrossL2Inbox": "0x4200000000000000000000000000000000000022",
+  "L2ToL2CrossDomainMessenger": "0x4200000000000000000000000000000000000023",
+
+  // Periphery
+  "L2NativeSuperchainERC20": "0x61a6eF395d217eD7C79e1B84880167a417796172"
+}
+```
diff --git a/docs/src/chain-environment/network-details/op-chain-b.md b/docs/src/chain-environment/network-details/op-chain-b.md
@@ -0,0 +1,84 @@
+<!-- omit in toc -->
+# OPChainB
+
+- [Network details](#network-details)
+- [Contract addresses](#contract-addresses)
+  - [L1 contracts](#l1-contracts)
+  - [L2 contracts](#l2-contracts)
+
+## Network details
+
+| **Parameter** | **Value**             |
+|---------------|-----------------------|
+| **Name**      | OPChainB              |
+| **Chain ID**  | 902                   |
+| **RPC URL**   | <http://127.0.0.1:9546> |
+
+## Contract addresses
+
+### L1 contracts
+
+```json
+{
+  "AddressManager": "0xafB51A0f73C8409AeA1207DF7f39885c927BeA46",
+  "AnchorStateRegistry": "0x05493149c84A71063f7948127bb931f8377F779C",
+  "AnchorStateRegistryProxy": "0xfd0269a716A59fF125Bd7eb65Cd3427C8555bab7",
+  "DelayedWETH": "0x49BBFf1629824A1e7993Ab5c17AFa45D24AB28c9",
+  "DelayedWETHProxy": "0xA63353128502269b4A4A4c2677fE316cd9ad4397",
+  "DisputeGameFactory": "0x20B168142354Cee65a32f6D8cf3033E592299765",
+  "DisputeGameFactoryProxy": "0x5F416fEb15c8B382d338FDBDb7D44967ca2b59BC",
+  "L1CrossDomainMessenger": "0x094e6508ba9d9bf1ce421fff3dE06aE56e67901b",
+  "L1CrossDomainMessengerProxy": "0xCB9768921831677Ae15cE4B64A10B94F49cD88E2",
+  "L1ERC721Bridge": "0x5C4F5e749A61a9503c4AAE8a9393e89609a0e804",
+  "L1ERC721BridgeProxy": "0xDCE41E6C0901586EE27Eac329EBD4b5fe5A7170d",
+  "L1StandardBridge": "0xb7900B27Be8f0E0fF65d1C3A4671e1220437dd2b",
+  "L1StandardBridgeProxy": "0x2D8543c236a4d626f54B51Fa8bc229a257C5143E",
+  "L2OutputOracle": "0x19652082F846171168Daf378C4fD3ee85a0D4A60",
+  "L2OutputOracleProxy": "0x006Af3fB62c4BE4fB0393995d364BbFe6b0F3CB2",
+  "Mips": "0xB3A0348310a0ff78E5FbDB7f14BB7d3e02d40773",
+  "OptimismMintableERC20Factory": "0x39Aea2Dd53f2d01c15877aCc2791af6BDD7aD567",
+  "OptimismMintableERC20FactoryProxy": "0x1A2A942d891e525D1Ab192578a378980729fD585",
+  "OptimismPortal": "0xb7461Fb347f68f9717e6fD12C8407dEcee063bdc",
+  "OptimismPortal2": "0xfcbb237388CaF5b08175C9927a37aB6450acd535",
+  "OptimismPortalProxy": "0xdfC9DEAbEEbDaa7620C71e2E76AEda32919DE5f2",
+  "PreimageOracle": "0x3bd7E801E51d48c5d94Ea68e8B801DFFC275De75",
+  "ProtocolVersions": "0xfbfD64a6C0257F613feFCe050Aa30ecC3E3d7C3F",
+  "ProtocolVersionsProxy": "0xE139cB0CDa5EF722870068ea331d0989776A7aDf",
+  "ProxyAdmin": "0xff5E6C2Af859f70B875BA59B958BEde60E36bf69",
+  "SafeProxyFactory": "0xb68f3B057fE3c6CdDF9DB35837Ea769FCc81978a",
+  "SafeSingleton": "0xeeB44D84d505AbD958d032e90704c56443eB3ED0",
+  "SuperchainConfig": "0x068E44eB31e111028c41598E4535be7468674D0A",
+  "SuperchainConfigProxy": "0x2ED4AA34573c36bF3856e597501aEf9d9Dc1687C",
+  "SystemConfig": "0x6167B477F8d9138aa509f54b2800443857e28c0f",
+  "SystemConfigProxy": "0x2Db03FE998D7c20E4B65afD1f50f04Ec4BfAb694",
+  "SystemOwnerSafe": "0xBF3830711B7c559042453B7546dB4736eFB4245e"
+}
+```
+
+### L2 contracts
+
+```json
+{
+  // OP Stack predeploys
+  "L2ToL1MessagePasser": "0x4200000000000000000000000000000000000016",
+  "L2CrossDomainMessenger": "0x4200000000000000000000000000000000000007",
+  "L2StandardBridge": "0x4200000000000000000000000000000000000010",
+  "L2ERC721Bridge": "0x4200000000000000000000000000000000000014",
+  "SequencerFeeVault": "0x4200000000000000000000000000000000000011",
+  "OptimismMintableERC20Factory": "0x4200000000000000000000000000000000000012",
+  "OptimismMintableERC721Factory": "0x4200000000000000000000000000000000000017",
+  "L1BlockInterop": "0x4200000000000000000000000000000000000015",
+  "GasPriceOracle": "0x420000000000000000000000000000000000000F",
+  "ProxyAdmin": "0x4200000000000000000000000000000000000018",
+  "BaseFeeVault": "0x4200000000000000000000000000000000000019",
+  "L1FeeVault": "0x420000000000000000000000000000000000001A",
+  "GovernanceToken": "0x4200000000000000000000000000000000000042",
+  "SchemaRegistry": "0x4200000000000000000000000000000000000020",
+  "EAS": "0x4200000000000000000000000000000000000021",
+  "CrossL2Inbox": "0x4200000000000000000000000000000000000022",
+  "L2ToL2CrossDomainMessenger": "0x4200000000000000000000000000000000000023",
+
+  // Periphery
+  "L2NativeSuperchainERC20": "0x61a6eF395d217eD7C79e1B84880167a417796172"
+}
+```
diff --git a/docs/src/examples/cross-chain-tictactoe.md b/docs/src/examples/cross-chain-tictactoe.md
@@ -0,0 +1 @@
+# Cross-chain tic-tac-toe
diff --git a/docs/src/getting-started/first-steps.md b/docs/src/getting-started/first-steps.md
@@ -0,0 +1,76 @@
+# First steps
+
+`supersim` allows testing multichain features **locally**. Previously, testing multichain features required complex docker setups or using a testnet.
+
+To see it in practice, let's first try sending some ETH from the L1 to the L2.
+
+## Deposit ETH from the L1 into the L2 (L1 to L2 message passing)
+
+### 1. Call `bridgeETH` function on the `L1StandardBridgeProxy` contract on the L1 (chain 900)
+
+Initiate a bridge transaction on the L1:
+
+```sh
+cast send 0xa01ae68902e205B420FD164435F299E07b0C778b "bridgeETH(uint32 _minGasLimit, bytes calldata _extraData)" 50000 0x --value 0.1ether --rpc-url http://127.0.0.1:8545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+```
+
+### 2. Check the balance on the L2 (chain 901)
+
+Verify that the ETH balance of the sender has increased on the L2:
+
+```sh
+cast balance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9545
+```
+
+Now that you know how to pass messages from the L1 to the L2, let's try a sending an L2 to L2 message!
+
+## Send an interoperable SuperchainERC20 token from chain 901 to 902 (L2 to L2 message passing)
+
+In a typical L2 to L2 cross-chain transfer, two transactions are required:
+
+1. Send transaction on the source chain – This initiates the token transfer on Chain 901.
+2. Relay message transaction on the destination chain – This relays the transfer details to Chain 902.
+
+To simplify this process, you can use the `--interop.autorelay` flag. This flag automatically triggers the relay message transaction once the initial send transaction is completed on the source chain, improving the developer experience by removing the need to manually send the relay message.
+
+### 1. Start `supersim` with the autorelayer enabled
+
+```
+supersim --interop.autorelay 
+```
+
+### 2. Mint tokens to transfer on chain 901
+
+Run the following command to mint 1000 tokens to the recipient address:
+
+```sh
+cast send 0x61a6eF395d217eD7C79e1B84880167a417796172 "mint(address _to, uint256 _amount)"  0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 1000  --rpc-url http://127.0.0.1:9545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+
+```
+
+### 3. Initiate the send transaction on chain 901
+
+Send the tokens from Chain 901 to Chain 902 using the following command:
+
+```sh
+cast send 0x61a6eF395d217eD7C79e1B84880167a417796172 "sendERC20(address _to, uint256 _amount, uint256 _chainId)" 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 1000 902 --rpc-url http://127.0.0.1:9545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+```
+
+### 4. Wait for the relayed message to appear on chain 902
+
+In a few seconds, you should see the RelayedMessage on chain 902:
+
+```sh
+# example
+INFO [08-30|14:30:14.698] L2ToL2CrossChainMessenger#RelayedMessage sourceChainID=901 destinationChainID=902 nonce=0 sender=0x61a6eF395d217eD7C79e1B84880167a417796172 target=0x61a6eF395d217eD7C79e1B84880167a417796172
+```
+
+### 5. Check the balance on chain 902
+
+Verify that the balance of the L2NativeSuperchainERC20 on chain 902 has increased:
+
+```sh
+cast balance --erc20 0x61a6eF395d217eD7C79e1B84880167a417796172 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9546
+```
+
+With the steps above, you've now successfully completed both an L1 to L2 ETH bridge and an L2 to L2 interoperable SuperchainERC20 token transfer, all done locally using `supersim`. This approach simplifies multichain testing, allowing you to focus on development without the need for complex setups or relying on external testnets.