Merge pull request #163 from scroll-tech/feb2024-bridge-updates-sepolia

Feb2024 Bridge Updates

Author: dghelm

public/locales/en/translation.json

@@ -113,6 +113,7 @@
       "introduction": "Introduction",
       "principles": "Principles",
       "scrollArchitecture": "Scroll Architecture",
+      "scrollUpgrades": "Scroll Upgrades",
       "overview": "Overview",
 
       "scrollChain": "Scroll Chain",

src/config/sidebar.ts

@@ -181,7 +181,13 @@ export const getSidebar = () => {
     technology: [
       {
         section: t("sidebar.technology.overview"),
-        contents: [{ title: t("sidebar.technology.scrollArchitecture"), url: formatUrl("technology") }],
+        contents: [
+          { title: t("sidebar.technology.scrollArchitecture"), url: formatUrl("technology") },
+          {
+            title: t("sidebar.technology.scrollUpgrades"),
+            url: "technology/overview/scroll-upgrades",
+          },
+        ],
       },
       {
         section: t("sidebar.technology.scrollChain"),

src/content/docs/en/developers/guides/estimating-gas-and-tx-fees.mdx

@@ -35,7 +35,7 @@ For a more comprehensive explanation and details on the formula, check the docum
 
 ## Interfacing with values
 
-To fetch these values and calculate the final fee, we’ll interact with Scroll’s public RPC and pre-deployed Smart Contract L1GasOracle.sol, which is deployed at [`TODO: 0x5300000000000000000000000000000000000002`](TODO: https://blockscout.scroll.io/address/0x5300000000000000000000000000000000000002)
+To fetch these values and calculate the final fee, we’ll interact with Scroll’s public RPC and pre-deployed Smart Contract `L1GasOracle.sol`, deployed at [`0x5300000000000000000000000000000000000002`](https://scrollscan.com/address/0x5300000000000000000000000000000000000002).
 
 For our example codebase, we make a Hardhat project and fetch values using the [Ethers.js](https://docs.ethers.org/v6/) library.
 

src/content/docs/en/developers/l1-and-l2-bridging.mdx

@@ -9,6 +9,7 @@ excerpt: "An overview of Scroll's Bridging architecture"
 ---
 
 import ClickToZoom from "../../../../components/ClickToZoom.astro"
+import Aside from "../../../../components/Aside.astro"
 import L1GatewayWHITE from "../../../../assets/images/developers/L1GatewayWHITE.png"
 import withdrawWHITE from "../../../../assets/images/developers/withdrawWHITE.png"
 
@@ -22,6 +23,7 @@ In addition to token transfers, the Scroll Messenger contract enables cross-chai
 
 ## L1 Gateway architecture
 
+
 <ClickToZoom src={L1GatewayWHITE} />
 
 There are many entry points from the user to the Scroll bridge. This will depend on what you want to do and how you want to do it. If you want to send ETH or ERC20 tokens, you should use the `GatewayRouter` . If you want to send NFTs, you should use the `L1ERC721Gateway` or `L1ERC1155Gateway`. If you want to send arbitrary data, you should use the `L1ScrollMessenger`. All Gateway transfers use the Scroll Messenger to send assets cross-chain, whose job is to append the transactions to the Message Queue for L2 inclusion.
@@ -32,4 +34,4 @@ There are many entry points from the user to the Scroll bridge. This will depend
 
 Regarding possible permissionlessly callable entry points, the L2 Gateway Architecture is very similar to L1. The difference is that when sending a message from L2, calling the `appendMessage` function will store the message in an append-only binary merkle tree (aka withdraw tree) in the `L2MessageQueue`. When a new message is sent to the `L2MessageQueue`, the relayer will detect it and store it in the database. When the block is finalized, it will generate a proof of the new merkle path and pass it to the L1geth node to execute on `L1ScrollMessenger` . All finalized withdraw roots will be stored in the rollup contract so we can verify the proof against them. In the next Scroll versions, the Relayer won't be needed since all users will be able to finalize the transaction on L1.
 
-In the upcoming sections, we will explore the technical aspects of the bridge, including the smart contract API required to utilize its capabilities. Detailed guides with code examples are provided in the Developer Guides section to assist developers and users in understanding and implementing these functionalities.
+In the upcoming sections, we will explore the technical aspects of the bridge, including the smart contract API required to utilize its capabilities. Detailed guides with code examples are provided in the Developer Guides section to assist developers and users in understanding and implementing these functionalities.

src/content/docs/en/developers/scroll-contracts.mdx

@@ -44,8 +44,8 @@ Use the table below to configure your Ethereum tools to the Scroll mainnet.
 
 ### ETH and ERC20 Bridge
 
-- L1 ERC20 Gateway Router: [`0xF8B1378579659D8F7EE5f3C929c2f3E332E41Fd6`](https://etherscan.io/address/0xF8B1378579659D8F7EE5f3C929c2f3E332E41Fd6)
-- L2 ERC20 Gateway Router: [`0x4C0926FF5252A435FD19e10ED15e5a249Ba19d79`](https://scrollscan.com/address/0x4C0926FF5252A435FD19e10ED15e5a249Ba19d79)
+- L1 Gateway Router: [`0xF8B1378579659D8F7EE5f3C929c2f3E332E41Fd6`](https://etherscan.io/address/0xF8B1378579659D8F7EE5f3C929c2f3E332E41Fd6)
+- L2 Gateway Router: [`0x4C0926FF5252A435FD19e10ED15e5a249Ba19d79`](https://scrollscan.com/address/0x4C0926FF5252A435FD19e10ED15e5a249Ba19d79)
 
 ### Advanced Bridge Contracts
 
@@ -68,8 +68,10 @@ Use the table below to configure your Ethereum tools to the Scroll mainnet.
 - ERC1155 Bridge
   - L1 ERC1155 Gateway: [`0xb94f7F6ABcb811c5Ac709dE14E37590fcCd975B6`](https://etherscan.io/address/0xb94f7F6ABcb811c5Ac709dE14E37590fcCd975B6)
   - L2 ERC1155 Gateway: [`0x62597Cc19703aF10B58feF87B0d5D29eFE263bcc`](https://scrollscan.com/address/0x62597Cc19703aF10B58feF87B0d5D29eFE263bcc)
-- Gas Oracle
-  - L2 Gas Oracle (deployed on Mainnet): [`0x987e300fDfb06093859358522a79098848C33852`](https://scrollscan.com/address/0x987e300fDfb06093859358522a79098848C33852)
+- Gas Oracle (deployed on Mainnet)
+  - L2 Gas Oracle (*soon to be deprecated*): [`0x987e300fDfb06093859358522a79098848C33852`](https://etherscan.io/address/0x987e300fDfb06093859358522a79098848C33852)
+  - *after [Feb '24 Bridge Upgrade](https://scroll.io/blog/protocol-upgrade-bridging-cost-reduction)*
+    - L2 Message Queue With Gas Price Oracle: [`0x0d7E906BD9cAFa154b048cFa766Cc1E54E39AF9B`](https://etherscan.io/address/0x0d7E906BD9cAFa154b048cFa766Cc1E54E39AF9B)
 
 ### L2 Predeploys
 
@@ -155,8 +157,8 @@ Use the table below to configure your Ethereum tools to the Scroll Sepolia Testn
 
 #### ETH and ERC20 Bridge
 
-- L1 ERC20 Gateway Router: [`0x13FBE0D0e5552b8c9c4AE9e2435F38f37355998a`](https://sepolia.etherscan.io/address/0x13FBE0D0e5552b8c9c4AE9e2435F38f37355998a)
-- L2 ERC20 Gateway Router: [`0x9aD3c5617eCAa556d6E166787A97081907171230`](https://sepolia.scrollscan.com/address/0x9aD3c5617eCAa556d6E166787A97081907171230)
+- L1 Gateway Router: [`0x13FBE0D0e5552b8c9c4AE9e2435F38f37355998a`](https://sepolia.etherscan.io/address/0x13FBE0D0e5552b8c9c4AE9e2435F38f37355998a)
+- L2 Gateway Router: [`0x9aD3c5617eCAa556d6E166787A97081907171230`](https://sepolia.scrollscan.com/address/0x9aD3c5617eCAa556d6E166787A97081907171230)
 
 #### Advanced Bridge Contracts
 
@@ -179,8 +181,9 @@ Use the table below to configure your Ethereum tools to the Scroll Sepolia Testn
 - ERC1155 Bridge
   - L1 ERC1155 Gateway: [`0xa5Df8530766A85936EE3E139dECE3bF081c83146`](https://sepolia.etherscan.io/address/0xa5Df8530766A85936EE3E139dECE3bF081c83146)
   - L2 ERC1155 Gateway: [`0xe17C9b9C66FAF07753cdB04316D09f52144612A5`](https://sepolia.scrollscan.com/address/0xe17C9b9C66FAF07753cdB04316D09f52144612A5)
-- Gas Oracle
-  - L2 Gas Oracle (deployed on Sepolia): [`0x247969F4fad93a33d4826046bc3eAE0D36BdE548`](https://sepolia.scrollscan.com/address/0x247969F4fad93a33d4826046bc3eAE0D36BdE548)
+- Gas Oracle (deployed on Sepolia)
+  - L1 Message Queue With Gas Price Oracle: [`0xF0B2293F5D834eAe920c6974D50957A1732de763`](https://sepolia.etherscan.io/address/0xF0B2293F5D834eAe920c6974D50957A1732de763)
+  - L2 Gas Oracle (*deprecated*): [`0x247969F4fad93a33d4826046bc3eAE0D36BdE548`](https://sepolia.etherscan.io/address/0x247969F4fad93a33d4826046bc3eAE0D36BdE548)
 
 #### L2 Predeploys
 

src/content/docs/en/developers/transaction-fees-on-scroll.mdx

@@ -140,7 +140,7 @@ Returns the latest known l1 base fee
 #### getL1Fee
 
 ```solidity
-function getL1Fee(bytes memory _data) external view returns (uint256);
+function getL1Fee(bytes memory data) external view returns (uint256);
 ```
 
 Computes the L1 portion of the fee based on the size of the RLP encoded input transaction, the current L1 base fee, and the various dynamic parameters.
@@ -165,10 +165,30 @@ Computes the amount of L1 gas used for a transaction. Adds the overhead which re
 | --------- | ----------------------------------------------------------- |
 | data      | Signed fully RLP-encoded transaction to get the L1 fee for. |
 
+## L1 Originated Transactions
+
+When messaging from L1 to L2, the user pays all transaction fees on L1. The user pays L1 gas fees, but because of this, doesn't need to pay Scroll an L1 Data Fee. They will need to account for L2 Execution Fees in their L1 transaction though, and will need to know how much L2 gas to pay.
+
+Contracts on L1 can use an L2 Gas Price Oracle deployed to the L1 to get the gas fee for a given transaction. The oracle also exposes the current l2BaseFee and estimated cross-domain message fee for a given gas limit.
+
+On mainnet, the `L2GasPriceOracle` is deployed at [`0x987e300fDfb06093859358522a79098848C33852`](https://etherscan.io/address/0x987e300fDfb06093859358522a79098848C33852).
+
+On Sepolia, an upgraded `L1MessageQueueWithGasPriceOracle` should be used, deployed to [`0xF0B2293F5D834eAe920c6974D50957A1732de763`](https://sepolia.etherscan.io/address/0xF0B2293F5D834eAe920c6974D50957A1732de763).
+
+If your system supports off-chain mechanisms, you can also call `eth_estimateGas` and `eth_gasPrice` on any Scroll RPC node to get an estimate of the gas required for a given transaction.
+
+<Aside type="danger" title="Upgrade Notice">
+After the February 2024 Bridge Upgrade, `L1GasPriceOracle` will be deprecated in favor of `L1MessageQueueWithGasPriceOracle`, which will be available at [`0x0d7E906BD9cAFa154b048cFa766Cc1E54E39AF9B`](https://etherscan.io/address/0x0d7E906BD9cAFa154b048cFa766Cc1E54E39AF9B).
+
+The upgrade is expected to be finalized on February 21, 2024, after a two-week timelock. Scroll Sepolia has already undergone this upgrade. Read more [here](https://scroll.io/blog/protocol-upgrade-bridging-cost-reduction).
+
+</Aside>
+{/* TODO: Add full documentation of key methods */}
+
 ## Future Roadmap
 
-Currently, the computation required for proof generation is completed by and subsidized by Scroll and various proving partners.
+Currently, the computation required for proof generation and gas for proof verification on L1 is subsidized by Scroll and various proving partners. It is partially covered by setting a floor to L2 Gas Price.
 
 As the prover network becomes decentralized, incentives for proof generation will need to be incorporated into the protocol for the system to be sustainable and scalable.
 
-We expect the final gas cost will include the cost of this proof generation. With further protocol optimization, this cost for the user should be minimal, as each proof covers many transactions.
+We expect the final gas cost will explicitly include the cost of this proof generation. With further protocol optimization, this cost for the user should be minimal, as each proof covers many transactions.

src/content/docs/en/technology/bridge/cross-domain-messaging.mdx

@@ -8,6 +8,7 @@ whatsnext: { "Deposit Gateways": "/technology/bridge/deposit-gateways/" }
 ---
 
 import ClickToZoom from "../../../../../components/ClickToZoom.astro"
+import Aside from "../../../../../components/Aside.astro"
 import ToggleElement from "../../../../../components/ToggleElement.astro"
 
 import L1ToL2 from "../_images/L1-to-L2.png"
@@ -22,6 +23,10 @@ Scroll has an arbitrary message passing bridge that enables token transfers and
 
 There are two primary approaches to sending a message from L1 to L2: sending arbitrary messages via `L1ScrollMessenger` and sending enforced transactions via `EnforcedTxGateway`. Both approaches allow users to initiate a L2 transaction on L1 and call arbitrary contracts on L2. For arbitrary messages, the sender of the L2 transactions is the aliased `L1ScrollMessenger` address. For enforced transactions, the L2 sender is an externally-owned account (EOA). In addition, we provide several standard token gateways to make it easier for users to deposit ETH and other standard tokens including ERC-20, ERC-677, ERC-721, and ERC-1155. In essence, these gateways encode token deposits into a message and send it to their counterparts on L2 through the `L1ScrollMessenger` contract. You can find more details about the L1 token gateways in the [Deposit Gateways](/technology/bridge/deposit-gateways).
 
+<Aside type="danger" title="">
+Enforced Transactions are not yet enabled on Scroll. In future upgrades, users will be able to use this functionality to bypass the `L1ScrollMessenger` and send messages directly to the `L1MessageQueue`.
+</Aside>
+
 As depicted in Figure 1, both arbitrary messages and enforced transactions are appended to the message queue stored in the `L1MessageQueue` contract. The `L1MessageQueue` contract provides two functions `appendCrossDomainMessage` and `appendEnforcedTransaction` for appending arbitrary messages and enforced transactions respectively.
 
 ```solidity
@@ -112,6 +117,10 @@ The deposited ETH of `value` amount is locked in the `L1ScrollMessenger` contrac
 
 ### Sending Enforced Transactions
 
+<Aside type="danger" title="">
+Enforced Transactions are not yet enabled on Scroll. In future upgrades, users will be able to use this functionality to bypass the `L1ScrollMessenger` and send messages directly to the `L1MessageQueue`.
+</Aside>
+
 The `EnforcedTxGateway` contract provides two `sendTransaction` functions to send an enforced transaction. In the first function, the sender of the generated `L1MessageTx` transaction is the transaction sender. On the other hand, the second function uses the passed `sender` address as the sender of the `L1MessageTx` transaction. This allows a third party to send an enforced transaction on behalf of the user and pay the relay fee. Note that the second function requires providing a valid signature of the generated `L1MessageTx` transaction that matches the `sender` address. Both `sendTransaction` functions enforce the sender to be an EOA account.
 
 <ToggleElement anchor="sendTransaction function signatures">
@@ -185,6 +194,13 @@ Because the `L2ScrollMessenger` contract records all L1 messages that were succe
 
 The contract `L2GasPriceOracle` deployed on L1 computes the relay fee of a message given its gas limit. This contract stores the `l2BaseFee` in its storage, which is updated by a dedicated relayer run by Scroll currently. The relay fee of L1-to-L2 messages is `gasLimit * l2BaseFee`.
 
+<Aside type="tip" title="Upgrade Notice">
+During the February 2024 Bridge Upgrade, `L2GasPriceOracle` will be deprecated, with its functionality moved into the `L1MessageQueueWithGasPriceOracle` contract.
+
+The upgrade is expected to be finalized on February 21, 2024, after a two-week timelock. Scroll Sepolia has already undergone this upgrade. Read more [here](https://scroll.io/blog/protocol-upgrade-bridging-cost-reduction).
+
+</Aside>
+
 ### Address Alias
 
 Due to the behavior of the `CREATE` opcode, it is possible that someone deploys a contract at the same address on L1 and L2 but with different bytecode. To avoid malicious users taking advantage of this, the bridge applies an address alias when the message sender is a contract on L1. The aliased sender address of the L1 message transaction is `l1_contract_address + offset` where the `offset` is `0x1111000000000000000000000000000000001111`.

src/content/docs/en/technology/bridge/withdraw-gateways.mdx

@@ -8,6 +8,7 @@ whatsnext: { "Sequencer": "/technology/sequencer/execution-node/" }
 ---
 
 import ClickToZoom from "../../../../../components/ClickToZoom.astro"
+import Aside from "../../../../../components/Aside.astro"
 import WithdrawWorkflow from "../_images/withdraw.png"
 
 This document describes how users and developers can utilize gateways to withdraw tokens from L2 to L1. We provide several gateways for standard tokens and a gateway router on L2, listed in the table below.