more doc changes

Author: kelemeno

docs/src/SUMMARY.md

@@ -81,7 +81,7 @@
   - [System Contracts](specs/zk_evm/system_contracts.md)
 - [Interop](specs/interop/overview.md)
   - [Interop Messages](specs/interop/interopmessages.md)
-  - [Bundles and Calls](specs/interop/bundlesandcalls.md)
+  - [Bundles and Calls](specs/interop/bundles_calls.md)
   - [Interop Transactions](specs/interop/interoptransactions.md)
 
 # Announcements

docs/src/specs/contracts/bridging/README.md

@@ -2,4 +2,9 @@
 
 - [Overview](./overview.md)
 - [Interop](./interop/interop.md)
+    - [Interop](./overview.md)
+    - [Interop Messages](./interopmessages.md)
+    - [Bundles and Calls](./bundles_calls.md)
+    - [Interop Transactions](./interoptransactions.md)
+
 - [Interop](./interop/forms_of_finality.md)

docs/src/specs/contracts/bridging/asset_router_and_ntv/asset_router.md

@@ -2,7 +2,16 @@
 
 [back to readme](../../README.md)
 
-The main job of the asset router is to be the central point of coordination for bridging. All crosschain token bridging is done between asset routers only and once the message reaches asset router, it then routes it to the corresponding asset handler.
+<!-- ## Asset router as the main asset bridging entrypoint
+
+The main entry for passing value between chains is the AssetRouter, it is responsible for facilitating bridging between multiple asset types. To read more in detail on how it works, please refer to custom [asset bridging documentation](./asset_router_and_ntv/overview.md).
+
+For the purpose of this document, it is enough to treat the Asset Router as a blackbox that is responsible for processing escrowing funds on the source chain and minting them on the destination chain.
+
+> For those that are aware of the [previous ZKsync architecture](https://github.com/code-423n4/2024-03-zksync/blob/main/docs/Smart%20contract%20Section/L1%20ecosystem%20contracts.md), its role is similar to L1SharedBridge that we had before. Note, however, that it is a different contract with much enhanced functionality. Also, note that the L1SharedBridge will NOT be upgraded to the L1AssetRouter. For more details about migration, please check out [the migration doc](../../upgrade_history/gateway_upgrade/gateway_diff_review.md). -->
+
+
+The main job of the asset router is to be the central point of coordination for asset bridging. All crosschain token bridging is done between asset routers only and once the message reaches asset router, it then routes it to the corresponding asset handler.
 
 In order to make this easier, all L2 chains have the asset router located on the same address on every chain. It is `0x10003` and it is pre-deployed contract. More on how it is deployed can be seen in the [Chain Genesis](../../chain_management/chain_genesis.md) section.
 
@@ -22,26 +31,4 @@ While the endgoal is to unify L1 and L2 asset routers, in reality, it may not be
 
 _This is the contract the previous L1SharedBridge will be upgraded to, so it should have the backwards compatible storage._
 
-### NativeTokenVault (L1/L2)
-
-NativeTokenVault is an asset handler that is available on all chains and is also predeployed. It is provides the functionality of the most basic bridging: locking funds on one chain and minting the bridged equivalent on the other one. On L2 chains NTV is predeployed at the `0x10004` address.
-
-The L1 and L2 versions of the NTV are almost identical in functionality, the main differences come from the differences of the deployment functionality in L1 and L2 envs, where the former uses standard CREATE2 and the latter uses low level calls to `CONTRACT_DEPLOYER`system contract.
-
-Also, the L1NTV has the following specifics:
-
-<!-- - It operates the `chainBalance` mapping, ensuring that the chains do not go beyond their balances.  -->
-- It allows recovering from failed L1→L2 transfers.
-- It needs to both be able to retrieve funds from the former L1SharedBridge (now this contract has L1Nullifier in its place), but also needs to support the old SDK that gives out allowance to the “l1 shared bridge” value returned from the API, i.e. in our case this is will the L1AssetRouter.
-
-### L2SharedBridgeLegacy
-
-L2AssetRouter has to be pre-deployed onto a specific address. The old L2SharedBridge will be upgraded to L2SharedBridgeLegacy contract. The main purpose of this contract is to ensure compatibility with the incoming deposits and re-route them to the shared bridge.
-
-This contract is never deployed for new chains.
-
-### Summary
-
-![image.png](./img/bridge_contracts.png)
-
 > New bridge contracts

docs/src/specs/contracts/bridging/asset_router_and_ntv/native_token_vault.md

@@ -0,0 +1,23 @@
+# Native Token Vault
+
+### NativeTokenVault (L1/L2)
+
+NativeTokenVault is an asset handler that is available on all chains and is also predeployed. It is provides the functionality of the most basic bridging: locking funds on one chain and minting the bridged equivalent on the other one. On L2 chains NTV is predeployed at the `0x10004` address.
+
+The L1 and L2 versions of the NTV are almost identical in functionality, the main differences come from the differences of the deployment functionality in L1 and L2 envs, where the former uses standard CREATE2 and the latter uses low level calls to `CONTRACT_DEPLOYER`system contract.
+
+Also, the L1NTV has the following specifics:
+
+<!-- - It operates the `chainBalance` mapping, ensuring that the chains do not go beyond their balances.  -->
+- It allows recovering from failed L1→L2 transfers.
+- It needs to both be able to retrieve funds from the former L1SharedBridge (now this contract has L1Nullifier in its place), but also needs to support the old SDK that gives out allowance to the “l1 shared bridge” value returned from the API, i.e. in our case this is will the L1AssetRouter.
+
+### L2SharedBridgeLegacy
+
+L2AssetRouter has to be pre-deployed onto a specific address. The old L2SharedBridge will be upgraded to L2SharedBridgeLegacy contract. The main purpose of this contract is to ensure compatibility with the incoming deposits and re-route them to the shared bridge.
+
+This contract is never deployed for new chains.
+
+### Summary
+
+![image.png](./img/bridge_contracts.png)

docs/src/specs/contracts/bridging/img/hyperbridging.png

@@ -54,7 +54,7 @@ contract InteropCenter {
 
 ```
 
-You can retrieve the `interopMessage` (which contains your entire payload) from the Gateway, or you can construct it
+You can retrieve the `interopMessage` (which contains your entire payload) from the chain, or you can construct it
 yourself using L1 data.
 
 Under the hood, this process calls the `destinationAddress` with the specified calldata.
@@ -76,46 +76,6 @@ sending interop messages from the `0x5bFF1...` account on chain A.
 
 ![msgdotsender.png](./img/msgdotsender.png)
 
-## Simple Example
-
-Imagine you have contracts on chains B, C, and D, and you’d like them to send "reports" to the Headquarters (HQ)
-contract on chain A every time a customer makes a purchase.
-
-```solidity
-// Deployed on chains B, C, D.
-contract Shop {
- /// Called by the customers when they buy something.
- function buy(uint256 itemPrice) {
-   // handle payment etc.
-   ...
-   // report to HQ
-   InteropCenter(INTEROP_ADDRESS).sendCall(
-    324,       // chain id of chain A,
-    0xc425..,  // HQ contract on chain A,
-    createCalldata("reportSales(uint256)", itemPrice), // calldata
-    0,         // no value
-  );
- }
-}
-
-// Deployed on chain A
-contract HQ {
-  // List of shops
-  mapping (address => bool) shops;
-  mapping (address => uint256) sales;
-  function addShop(address addressOnChain, uint256 chainId) onlyOwner {
-    // Adding aliased accounts.
-   shops[address(keccak(addressOnChain || chainId))] = true;
-  }
-
-  function reportSales(uint256 itemPrice) {
-    // only allow calls from our shops (their aliased accounts).
-   require(shops[msg.sender]);
-   sales[msg.sender] += itemPrice;
-  }
-}
-```
-
 #### Who is paying for gas? How does this Call get to the destination chain
 
 At this level, the **InteropCall** acts like a hitchhiker — it relies on someone (anyone) to pick it up, execute it, and
@@ -177,58 +137,6 @@ contract InteropCenter {
 }
 ```
 
-### Cross Chain Swap Example
-
-Imagine you want to perform a swap on chain B, exchanging USDC for PEPE, but all your assets are currently on chain A.
-
-This process would typically involve four steps:
-
-1. Transfer USDC from chain A to chain B.
-2. Set allowance for the swap.
-3. Execute the swap.
-4. Transfer PEPE back to chain A.
-
-Each of these steps is a separate "call," but you need them to execute in exactly this order and, ideally, atomically.
-If the swap fails, you wouldn’t want the allowance to remain set on the destination chain.
-
-Below is an example of how this process could look (note that the code is pseudocode; we’ll explain the helper methods
-required to make it work in a later section).
-
-```solidity
-bundleId = InteropCenter(INTEROP_CENTER).startBundle(chainD);
-// This will 'burn' the 1k USDC, create the special interopCall
-// when this call is executed on chainD, it will mint 1k USDC there.
-// BUT - this interopCall is tied to this bundle id.
-USDCBridge.transferWithBundle(
-  bundleId,
-  chainD,
-  aliasedAccount(this(account), block.chain_id),
-  1000);
-
-
-// This will create interopCall to set allowance.
-InteropCenter.addToBundle(bundleId,
-            USDCOnDestinationChain,
-            createCalldata("approve", 1000, poolOnDestinationChain),
-            0);
-// This will create interopCall to do the swap.
-InteropCenter.addToBundle(bundleId,
-            poolOnDestinationChain,
-            createCalldata("swap", "USDC_PEPE", 1000, ...),
-            0)
-// And this will be the interopcall to transfer all the assets back.
-InteropCenter.addToBundle(bundleId,
-            pepeBridgeOnDestinationChain,
-            createCalldata("transferAll", block.chain_id, this(account)),
-            0)
-
-
-bundleHash = interopCenter.finishAndSendBundle(bundleId);
-```
-
-In the code above, we created a bundle that anyone can execute on the destination chain. This bundle will handle the
-entire process: minting, approving, swapping, and transferring back.
-
 ### Bundle Restrictions
 
 When starting a bundle, if you specify the `executionAddress`, only that account will be able to execute the bundle on

docs/src/specs/contracts/bridging/img/message_root.png

@@ -1,6 +1,7 @@
 # Cross Chain Paymaster
 
 [back to readme](../../README.md)
+
 We want to allow the automatic execution of cross-chain txs. I.e. the user should not have to interact with the destination chain. We use triggers for this. The cross chain txs can be triggered on the origin chain, if this is the case then there is a feePaymentBundle and an execution bundle this is a general solution, that allows multiple options for paying for gas.
 
 - Easiest. Pay a required baseTokenAmount on the sender chain (in the baseToken on the destination chain). The same amount will be minted on the destination chain. e.g. [here](../../../../../../core/tests/ts-integration/tests/interop.test.ts#L526)

docs/src/specs/contracts/bridging/interop_for_devs/bundlesandcalls.md renamed to docs/src/specs/contracts/bridging/interop/bundles_calls.md

@@ -0,0 +1,91 @@
+## Simple Example
+
+Imagine you have contracts on chains B, C, and D, and you’d like them to send "reports" to the Headquarters (HQ)
+contract on chain A every time a customer makes a purchase.
+
+```solidity
+// Deployed on chains B, C, D.
+contract Shop {
+ /// Called by the customers when they buy something.
+ function buy(uint256 itemPrice) {
+   // handle payment etc.
+   ...
+   // report to HQ
+   InteropCenter(INTEROP_ADDRESS).sendCall(
+    324,       // chain id of chain A,
+    0xc425..,  // HQ contract on chain A,
+    createCalldata("reportSales(uint256)", itemPrice), // calldata
+    0,         // no value
+  );
+ }
+}
+
+// Deployed on chain A
+contract HQ {
+  // List of shops
+  mapping (address => bool) shops;
+  mapping (address => uint256) sales;
+  function addShop(address addressOnChain, uint256 chainId) onlyOwner {
+    // Adding aliased accounts.
+   shops[address(keccak(addressOnChain || chainId))] = true;
+  }
+
+  function reportSales(uint256 itemPrice) {
+    // only allow calls from our shops (their aliased accounts).
+   require(shops[msg.sender]);
+   sales[msg.sender] += itemPrice;
+  }
+}
+```
+
+### Cross Chain Swap Example
+
+Imagine you want to perform a swap on chain B, exchanging USDC for PEPE, but all your assets are currently on chain A.
+
+This process would typically involve four steps:
+
+1. Transfer USDC from chain A to chain B.
+2. Set allowance for the swap.
+3. Execute the swap.
+4. Transfer PEPE back to chain A.
+
+Each of these steps is a separate "call," but you need them to execute in exactly this order and, ideally, atomically.
+If the swap fails, you wouldn’t want the allowance to remain set on the destination chain.
+
+Below is an example of how this process could look (note that the code is pseudocode; we’ll explain the helper methods
+required to make it work in a later section).
+
+```solidity
+bundleId = InteropCenter(INTEROP_CENTER).startBundle(chainD);
+// This will 'burn' the 1k USDC, create the special interopCall
+// when this call is executed on chainD, it will mint 1k USDC there.
+// BUT - this interopCall is tied to this bundle id.
+USDCBridge.transferWithBundle(
+  bundleId,
+  chainD,
+  aliasedAccount(this(account), block.chain_id),
+  1000);
+
+
+// This will create interopCall to set allowance.
+InteropCenter.addToBundle(bundleId,
+            USDCOnDestinationChain,
+            createCalldata("approve", 1000, poolOnDestinationChain),
+            0);
+// This will create interopCall to do the swap.
+InteropCenter.addToBundle(bundleId,
+            poolOnDestinationChain,
+            createCalldata("swap", "USDC_PEPE", 1000, ...),
+            0)
+// And this will be the interopcall to transfer all the assets back.
+InteropCenter.addToBundle(bundleId,
+            pepeBridgeOnDestinationChain,
+            createCalldata("transferAll", block.chain_id, this(account)),
+            0)
+
+
+bundleHash = interopCenter.finishAndSendBundle(bundleId);
+```
+
+In the code above, we created a bundle that anyone can execute on the destination chain. This bundle will handle the
+entire process: minting, approving, swapping, and transferring back.