feat: docs for new release (matter-labs#61)

* Starting writing up * Start to change the docs * Some more basic documentation * basic AA documentation * Add some basic description of the system contracts * Update sdk docs (matter-labs#63) * Update changed methods * Add new methods to the docs * Use USDC_L2_ADDRESS * Update docs/api/js/getting-started.md Co-authored-by: barakshani <[email protected]> * Apply suggestions from code review Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/aa.md Co-authored-by: barakshani <[email protected]> * More appropriate use of AA/account * Vb docs new realease (matter-labs#62) * Add base info about L2 -> L1 * Update L1 -> L2 communication section * Write a couple of words about L2 -> L1 communication * Add description of the L2 -> L1 communication interfaces * Set todos * Remove method for getting l1 withdraw tx * Fix l1 -> l2 communication guide * Remove examples from the l2 -> l1 guide * Update docs/dev/guide/l2-l1.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Fix typos & fix imports in code examples * Add basic solitiy example of using l2 -> l1 messaging * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Fix comments * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> Co-authored-by: Stanislav Bezkorovainyi <[email protected]> Co-authored-by: barakshani <[email protected]> * Vb docs new realease (matter-labs#64) * Add base info about L2 -> L1 * Update L1 -> L2 communication section * Write a couple of words about L2 -> L1 communication * Add description of the L2 -> L1 communication interfaces * Set todos * Remove method for getting l1 withdraw tx * Fix l1 -> l2 communication guide * Remove examples from the l2 -> l1 guide * Update docs/dev/guide/l2-l1.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: Stanislav Bezkorovainyi <[email protected]> * Fix typos & fix imports in code examples * Add basic solitiy example of using l2 -> l1 messaging * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Fix comments * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Fix comments * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> * Apply more suggestions * Fix issue & add typescript example Co-authored-by: Stanislav Bezkorovainyi <[email protected]> Co-authored-by: barakshani <[email protected]> * fmt + new api endpoint * Slightly better description of L2->L1 proffs * Disclaimer for the l1 governance tutorial * change warning * Fix typos & add dummy section of bridging * Use less confusing titles * mark tutorials as non-working * capital letters * Update docs/api/api.md Co-authored-by: barakshani <[email protected]> * Update docs/api/api.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/guide/l2-l1.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> * Update docs/dev/zksync-v2/l1-l2-interop.md Co-authored-by: barakshani <[email protected]> Co-authored-by: Stanislav Bezkorovainyi <[email protected]> Co-authored-by: Lyova Potyomkin <[email protected]> Co-authored-by: barakshani <[email protected]> Co-authored-by: Vlad Bochok <[email protected]> Co-authored-by: vladbochok <[email protected]>
qingfeng · Jun 22, 2022 · 17f54b3 · 17f54b3
1 parent 98bdf05
commit 17f54b3
Show file tree

Hide file tree

Showing 32 changed files with 577 additions and 1,069 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -129,10 +129,10 @@ module.exports = {
           collapsable: false,
           children: [
             "/dev/zksync-v2/overview.md",
+            "/dev/zksync-v2/system-contracts.md",
             "/dev/zksync-v2/handling-of-eth.md",  
             "/dev/zksync-v2/fee-model.md",
-            "/dev/zksync-v2/tx-types.md", 
-            "/dev/zksync-v2/tx-formats.md", 
+            "/dev/zksync-v2/tx-types.md",
             "/dev/zksync-v2/contracts.md",
             "/dev/zksync-v2/aa.md",
             "/dev/zksync-v2/blocks-and-time.md", 
@@ -141,6 +141,7 @@ module.exports = {
             "/dev/zksync-v2/temp-limits.md", 
             "/dev/zksync-v2/decentralization-roadmap.md", 
             "/dev/zksync-v2/l1-l2-interop.md", 
+            "/dev/zksync-v2/bridging-funds.md", 
           ],
         },
         {
@@ -155,6 +156,7 @@ module.exports = {
             "/dev/guide/front-end-integration.md", 
             "/dev/guide/l1-l2.md",
             "/dev/guide/l2-l1.md",
+            "/dev/guide/build-custom-bridge.md",
             "/dev/guide/cross-chain-tutorial.md"
           ],
         },

diff --git a/docs/api/api.md b/docs/api/api.md
@@ -2,7 +2,7 @@
 
 zkSync 2.0 fully supports standard [Ethereum JSON-RPC API](https://eth.wiki/json-rpc/API).
 
-As long as the code does not involve deploying new smart contracts (they can only be deployed using EIP712 transactions, more on that [below](#eip712)), _no changes for the codebase are needed._
+As long as the code does not involve deploying new smart contracts (they can only be deployed using EIP712 transactions, more on that [below](#eip712)) or EIP1559-specific features, _no changes for the codebase are needed._
 
 It is possible to continue using the SDK that is currently in use. Users will continue paying fees in ETH, and the UX will be identical to the one on Ethereum.
 
@@ -15,33 +15,30 @@ To specify additional fields, like the token for fee payment or provide the byte
 ```json
 "fee": {
   "fee_token": "0x0000...0000",
-  "ergs_per_storage_limit": 100000,
   "ergs_per_pubdata_limit": 1000
 },
-"withdraw_token": "0x00000...00000",
 "factory_deps": ["0x..."]
 ```
 
-- `fee` is a field that describes the token in which the fee is to be paid, and defines the limits on the price in `ergs` per storage slot write and per publishing a single pubdata byte.
-- `withdraw_token` is a parameter that should be only supplied for `Withdraw` operations. _Most likely will be removed after the testnet._
-- `factory_deps` is a field that should be a non-empty array of `bytes` only for `Deploy` transactions. It should contain the bytecode of the contract being deployed. If the contract being deployed is a factory contract, i.e. it can deploy other contracts, the array should also contain the bytecodes of the contracts which can be deployed by it.
+- `fee` is a field that describes the token in which the fee is to be paid, and defines the limits on the price in `ergs` per publishing a single pubdata byte.
+- `factory_deps` is a field that should be a non-empty array of `bytes` for deployment transactions. It should contain the bytecode of the contract being deployed. If the contract being deployed is a factory contract, i.e. it can deploy other contracts, the array should also contain the bytecodes of the contracts which can be deployed by it.
 
-To let the server recognize EIP712 transactions, the `transaction_type` field is equal to `112` (unfortunately the number `712` can not be used as the `transaction_type` since the type has to be one byte long).
+To let the server recognize EIP712 transactions, the `transaction_type` field is equal to `113` (unfortunately the number `712` can not be used as the `transaction_type` since the type has to be one byte long).
 
 Instead of signing the RLP-encoded transaction, the user signs the following typed EIP712 structure:
 
-| Field name     | Type      |
-| -------------- | --------- |
-| to             | `address` |
-| nonce          | `uint256` |
-| value          | `uint256` |
-| data           | `bytes`   |
-| gasPrice       | `uint256` |
-| gasLimit       | `uint256` |
-| ergsPerStorage | `uint256` |
-| ergsPerPubdata | `uint256` |
-| feeToken       | `address` |
-| withdrawToken  | `address` |
+| Field name              | Type      |
+| ----------------------- | --------- |
+| txType                  | `uint8`   |
+| to                      | `address` |
+| value                   | `uint256` |
+| data                    | `bytes`   |
+| feeToken                | `address` |
+| ergsLimit               | `uint256` |
+| gasLimit                | `uint256` |
+| ergsPerPubdataByteLimit | `uint256` |
+| ergsPrice               | `uint256` |
+| nonce                   | `uint256` |
 
 These fields are conveniently handled by our [SDK](./js/features.md).
 
@@ -95,20 +92,6 @@ None.
 
 `12`
 
-### `zks_getL1WithdrawalTx`
-
-Given the hash of the withdrawal transaction on layer 2, returns the hash of the layer 1 transaction that executed the withdrawal or `null` if the withdrawal has not been executed yet.
-
-### Input parameters
-
-| Parameter       | Type      | Description                             |
-| --------------- | --------- | --------------------------------------- |
-| withdrawal_hash | `bytes32` | The hash of the withdrawal transaction. |
-
-### Output format
-
-`"0xd8a8165ada7ec780364368bf28e473d439e41c4c95164c23368d368cc3730ea7"`
-
 ### `zks_getConfirmedTokens`
 
 Given `from` and `limit`, returns the information about the confirmed tokens with ids in the interval `[from..from+limit-1]`. Confirmed tokens are native tokens that are considered legit by the zkSync team. This method will be mostly used by the zkSync team internally.
@@ -124,7 +107,7 @@ The tokens are returned in alphabetical order by their symbol, so basically, the
 
 ### Output format
 
-```
+```json
 [
   {
     "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
@@ -161,6 +144,43 @@ Given a token address, returns whether it can be used to pay fees.
 
 `true`
 
+### `zks_getL2ToL1MsgProof`
+
+Given a block, a sender and a message, returns the proof for the message sent via the L1Messenger system contract.
+
+### Input parameters
+
+| Parameter | Type      | Description                                                                               |
+| --------- | --------- | ----------------------------------------------------------------------------------------- |
+| block     | `uint32`  | The number of the block where the message was emitted.                                    |
+| sender    | `address` | The sender of the message (i.e. the account that called the L1Messenger system contract). |
+| msg       | `uint256` | The keccak256 hash of the message that was sent.                                          |
+
+### Output format
+
+If there was no such message, the returned value is `null`.
+
+Otherwise, the object of the following format is returned:
+
+```json
+{
+  "id": 0,
+  "proof": [
+    "0x66687aadf862bd776c8fc18b8e9f8e20089714856ee233b3902a591d0d5f2925",
+    "0x2eeb74a6177f588d80c0c752b99556902ddf9682d0b906f5aa2adbaf8466a4e9",
+    "0x1223349a40d2ee10bd1bebb5889ef8018c8bc13359ed94b387810af96c6e4268",
+    "0x5b82b695a7ac2668e188b75f7d4fa79faa504117d1fdfcbe8a46915c1a8a5191"
+  ],
+  "root": "0x6a420705824f0a3a7e541994bc15e14e6a8991cd4e4b2d35c66f6e7647760d97"
+}
+```
+
+The `id` is the position of the leaf in the Merkle tree of L2->L1 messages for the block. The `proof` is the merkle proof for the message, while the `root ` is the root of the merkle tree of L2->L1 messages. Please note, that the merkle tree uses _sha256_ for the trees.
+
+You do not need to care about the intrinsics, since the returned `id` and `proof` can be used rightaway for interacting with zkSync smart contract.
+
+A nice example of using this endpoint via our SDK can be found [here](../dev/guide/l2-l1.md).
+
 <!-- TODO: uncomment once fixed --->
 <!-- ### `zks_getTokenPrice`
 

diff --git a/docs/api/hardhat/getting-started.md b/docs/api/hardhat/getting-started.md
@@ -27,10 +27,10 @@ For this tutorial, the following programs must be installed:
 mkdir greeter-example
 cd greeter-example
 yarn init -y
-yarn add -D typescript ts-node ethers zksync-web3 hardhat @matterlabs/[email protected] @matterlabs/hardhat-zksync-deploy@0.2
+yarn add -D typescript ts-node ethers zksync-web3 hardhat @matterlabs/[email protected] @matterlabs/hardhat-zksync-deploy@0.3
 ```
 
-`typescript` and `ts-node` are optional - plugins will work fine in vanilla JavaScript environment. Although, please note that this tutorial *does* use TypeScript.
+`typescript` and `ts-node` are optional - plugins will work fine in vanilla JavaScript environment. Although, please note that this tutorial _does_ use TypeScript.
 
 2. Create the `hardhat.config.ts` file and paste the following code within it:
 
@@ -174,10 +174,7 @@ This section explains how to pay fees in `USDC` token as an example.
 1. After making sure that the wallet has some Görli `USDC` on L1, change the depositing code to the following:
 
 ```typescript
-const USDC_ADDRESS = "0xd35cceead182dcee0f148ebac9447da2c4d449c4";
-const USDC_DECIMALS = 6;
-
-const deploymentFee = await deployer.estimateDeployFee(artifact, [greeting], USDC_ADDRESS);
+const deploymentFee = await deployer.estimateDeployFee(artifact, [greeting], USDC_L2_ADDRESS);
 // Deposit funds to L2.
 const depositHandle = await deployer.zkWallet.deposit({
   to: deployer.zkWallet.address,
@@ -198,6 +195,7 @@ await depositHandle.wait();
 2. To output the fee in a human-readable format:
 
 ```typescript
+const USDC_DECIMALS = 6;
 const parsedFee = ethers.utils.formatUnits(deploymentFee.toString(), USDC_DECIMALS);
 console.log(`The deployment will cost ${parsedFee} USDC`);
 ```
@@ -207,15 +205,15 @@ Please note that the fees on the testnet do not correctly represent the fees on
 3. Now pass `USDC` as the `feeToken` to the deployment transaction:
 
 ```typescript
-const greeterContract = await deployer.deploy(artifact, [greeting], { feeToken: USDC_ADDRESS });
+const greeterContract = await deployer.deploy(artifact, [greeting], { feeToken: USDC_L2_ADDRESS });
 ```
 
 4. To pay fees in USDC for smart contract interaction, supply the fee token in the `customData` override:
 
 ```typescript
 const setNewGreetingHandle = await greeterContract.setGreeting(newGreeting, {
   customData: {
-    feeToken: USDC_ADDRESS,
+    feeToken: USDC_L2_ADDRESS,
   },
 });
 ```
@@ -228,7 +226,6 @@ import * as ethers from "ethers";
 import { HardhatRuntimeEnvironment } from "hardhat/types";
 import { Deployer } from "@matterlabs/hardhat-zksync-deploy";
 
-const USDC_ADDRESS = "0xd35cceead182dcee0f148ebac9447da2c4d449c4";
 const USDC_DECIMALS = 6;
 
 // An example of a deploy script that will deploy and call a simple contract.
@@ -243,12 +240,12 @@ export default async function (hre: HardhatRuntimeEnvironment) {
   const artifact = await deployer.loadArtifact("Greeter");
 
   const greeting = "Hi there!";
-  const deploymentFee = await deployer.estimateDeployFee(artifact, [greeting], USDC_ADDRESS);
+  const deploymentFee = await deployer.estimateDeployFee(artifact, [greeting], USDC_L2_ADDRESS);
 
   // Deposit funds to L2
   const depositHandle = await deployer.zkWallet.deposit({
     to: deployer.zkWallet.address,
-    token: USDC_ADDRESS,
+    token: USDC_L2_ADDRESS,
     amount: deploymentFee.mul(2),
     approveERC20: true,
   });
@@ -257,10 +254,10 @@ export default async function (hre: HardhatRuntimeEnvironment) {
 
   // Deploy this contract. The returned object will be of a `Contract` type, similarly to ones in `ethers`.
   // `greeting` is an argument for contract constructor.
-  const parsedFee = ethers.utils.formatUnits(deploymentFee.toString(), USDC_DECIMALS);
+  const parsedFee = ethers.utils.formatUnits(deploymentFee.toString(), USDC_L2_DECIMALS);
   console.log(`The deployment will cost ${parsedFee} USDC`);
 
-  const greeterContract = await deployer.deploy(artifact, [greeting], { feeToken: USDC_ADDRESS });
+  const greeterContract = await deployer.deploy(artifact, [greeting], { feeToken: USDC_L2_ADDRESS });
 
   // Show the contract info.
   const contractAddress = greeterContract.address;
@@ -278,7 +275,7 @@ export default async function (hre: HardhatRuntimeEnvironment) {
   const newGreeting = "Hey guys";
   const setNewGreetingHandle = await greeterContract.setGreeting(newGreeting, {
     customData: {
-      feeToken: USDC_ADDRESS,
+      feeToken: USDC_L2_ADDRESS,
     },
   });
   await setNewGreetingHandle.wait();

diff --git a/docs/api/hardhat/testing.md b/docs/api/hardhat/testing.md
@@ -1,6 +1,6 @@
 # Local testing
 
-Sometimes there is a need to test contracts in a local environment for network latency or fee reasons. 
+Sometimes there is a need to test contracts in a local environment for network latency or fee reasons.
 
 zkSync team provides a dockerized local setup for this purpose.
 
@@ -65,20 +65,18 @@ To use custom Postgres database or Layer 1, you should change the environment pa
 
 ```yml
 environment:
-    - DATABASE_URL=postgres://postgres@postgres/zksync_local
-    - ETH_CLIENT_WEB3_URL=http://geth:8545
+  - DATABASE_URL=postgres://postgres@postgres/zksync_local
+  - ETH_CLIENT_WEB3_URL=http://geth:8545
 ```
 
 - `DATABASE_URL` is the URL to the Postgres database.
 - `ETH_CLIENT_WEB3_URL` is the URL to the HTTP JSON-RPC interface of the L1 node.
 
-
 ## Testing with `mocha` + `chai`
 
 Please note, that since the zkSync node URL is provided in the `hardhat.config.ts`, the best way to use different URLs for production deployment and local testing is to use environment variables. The standard way is to set `NODE_ENV=test` environment variable before invoking the tests.
 
-
-1. Create a new hardhat project and follow the contracts' compilation guide from the [getting started](./getting-started.md) page (steps 1 to 5 of the **Initializing the project**  section).
+1. Create a new hardhat project and follow the contracts' compilation guide from the [getting started](./getting-started.md) page (steps 1 to 5 of the **Initializing the project** section).
 2. To add the test frameworks, run the following command:
 
 ```
@@ -133,8 +131,8 @@ module.exports = {
     // To compile with zksolc, this must be the default network.
     hardhat: {
       zksync: true,
-    }
-  }
+    },
+  },
 };
 ```