Chore: update Technical reference section, remove WIP pages warnings,…

… and adds best practices page (matter-labs#609) * chore: closes DEVRL-109 and DEVRL-110 * chore: updates technical reference page, related to DEVRL-110 * fix: typo * Update docs/dev/building-on-zksync/best-practices.md Co-authored-by: Antonio <[email protected]> --------- Co-authored-by: Antonio <[email protected]>
FilipTxFusion · Jun 29, 2023 · b16c1b4 · b16c1b4
1 parent db13f03
commit b16c1b4
Show file tree

Hide file tree

Showing 8 changed files with 183 additions and 212 deletions.
diff --git a/docs/.vuepress/sidebar/en.ts b/docs/.vuepress/sidebar/en.ts
@@ -12,6 +12,7 @@ export const enSidebar = sidebar({
       link: "/dev/building-on-zksync/hello-world.md", 
       children: [ "/dev/building-on-zksync/hello-world.md", 
                   "/dev/building-on-zksync/interacting.md",
+                  "/dev/building-on-zksync/best-practices.md",
                   "/dev/building-on-zksync/useful-address.md", ],
     },
     {

diff --git a/docs/dev/README.md b/docs/dev/README.md
@@ -7,21 +7,22 @@ Our docs are open source so feel free to suggest new topics, add new content, or
 ## Getting started
 
 - [Hello world](./building-on-zksync/hello-world.md): Build a full dApp using the zkSync Era development toolbox.
-- [Interacting with zkSync Era](./building-on-zksync/interacting.md): this page is under development.
-- [Useful addresses](./building-on-zksync/useful-address.md)
+- [Interacting with zkSync Era](./building-on-zksync/interacting.md): Learn the essentials of interacting with zkSync Era, utilizing zkSync SDKs, and connecting to the network via Metamask.
+- [Best practices and considerations](./building-on-zksync/best-practices.md): Understand the recommended ways of working with zkSync Era to optimize performance and security. Be aware of specific considerations when developing.
+- [Useful addresses](./building-on-zksync/useful-address.md): Comprehensive list of essential addresses for developers building on zkSync.
 
 ## How to
 
-- [Estimate gas](./how-to/estimate-gas.md)
-- [Send an L1 to L2 transaction](./how-to/send-transaction-l1-l2.md)
-- [Send an L2 to L1 message](./how-to/send-message-l2-l1.md)
-- [Transfer a token on L2](./how-to/transfer-token-l2.md)
-- [Verify contracts with Hardhat](./how-to/verify-contracts.md)
+- [Estimate gas](./how-to/estimate-gas.md): Learn to implement gas estimation for various transactions (L1 to L1, L1 to L2, L2 to L2) in the zkSync environment.
+- [Send an L1 to L2 transaction](./how-to/send-transaction-l1-l2.md): Detailed guide for initiating an L1 to L2 transaction.
+- [Send an L2 to L1 message](./how-to/send-message-l2-l1.md): Understand the process of sending an L2 to L1 message.
+- [Transfer a token on L2](./how-to/transfer-token-l2.md): Discover the steps for transferring a token within L2.
+- [Verify contracts with Hardhat](./how-to/verify-contracts.md): Contract verification using the zkSync Hardhat plugin.
 
 ## Tutorials
 
-- [Cross-chain governance](./tutorials/cross-chain-tutorial.md)
-- [Account abstraction multisig](./tutorials/custom-aa-tutorial.md)
-- [Daily spending limit account](./tutorials/aa-daily-spend-limit.md)
-- [Building a custom paymaster](./tutorials/custom-paymaster-tutorial.md)
-- [USDC paymaster tutorial with API3 dAPIs](./tutorials/api3-usd-paymaster-tutorial.md)
+- [Cross-chain governance](./tutorials/cross-chain-tutorial.md): Facilitate cross-chain governance between L1 and L2 with this comprehensive guide.
+- [Account abstraction multisig](./tutorials/custom-aa-tutorial.md): Build, deploy, and test a 2-of-2 multi-signature account using a factory contract.
+- [Daily spending limit account](./tutorials/aa-daily-spend-limit.md): Create a smart contract account with a daily spending limit using zkSync Era's account abstraction support.
+- [Building a custom paymaster](./tutorials/custom-paymaster-tutorial.md): Construct a custom paymaster to enable users to pay fees with any ERC20 token.
+- [USDC paymaster tutorial with API3 dAPIs](./tutorials/api3-usd-paymaster-tutorial.md): Develop a custom paymaster leveraging API3 data feeds, allowing users to pay fees with mockUSDC ERC20 token.
diff --git a/docs/dev/building-on-zksync/best-practices.md b/docs/dev/building-on-zksync/best-practices.md
@@ -0,0 +1,113 @@
+# Best practices and considerations
+
+:::info Important Recommendations
+Before diving into development on zkSync Era, it's crucial to consider the following recommendations. These best practices will help you optimize your code, ensure security, and align with the unique characteristics of zkSync Era.
+:::
+
+## Using `call` over `.send` or `.transfer`
+
+Avoid using `payable(addr).send(x)`/`payable(addr).transfer(x)` because the 2300 gas stipend may not be enough for such calls, especially if it involves state changes that require a large amount of L2 gas for data. Instead, we recommend using `call`.
+
+Instead of:
+
+```solidity
+payable(addr).send(x) // or
+payable(addr).transfer(x)
+```
+
+Use instead:
+
+```solidity
+(bool s, ) = addr.call{value: x}("");
+require(s);
+```
+
+This converts the `send`/`transfer` functionality to `call` and [avoids potential security risks outlined here.](https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/).
+
+:::note Be aware of reentrancy
+While `.call` offers more flexibility compared to `.send` or `.transfer`, developers should be aware that `.call` does not provide the same level of reentrancy protection as `.transfer`/`.send`. It's crucial to adhere to best practices like the checks-effects-interactions pattern and/or use reentrancy guard protection to secure your contracts against reentrancy attacks. It can help ensure the robustness and security of your smart contracts on the zkEVM, even under unexpected conditions.
+:::
+
+## Use the proxy pattern at the early stage of the protocol
+
+zkSync Era is based on the zk-friendly VM. That’s why we provide our compiler that compiles standard Solidity
+code to zkEVM bytecode.
+
+While we have extensive test coverage to ensure EVM compatibility, issues may still appear.
+We will implement the patches for these in a timely manner.
+
+In order to apply compiler bug fix, you need to upgrade your smart contract. We advise using the
+Proxy pattern for a few months after your first deployment on zkSync Era, even if you plan to migrate to the immutable
+contract in the future.
+
+:::tip zkSync Upgradeable plugin
+
+- The [hardhat-zksync-upgradeable plugin](https://era.zksync.io/docs/api/hardhat/hardhat-zksync-upgradable.html) is now available to help you create proxies.
+  :::
+
+## Do not rely on EVM gas logic
+
+zkSync Era has a distinctive gas logic compared to Ethereum. There are two main drivers:
+
+- We have a state-diff-based data availability, which means that the price for the execution depends on the L1 gas price.
+- zkEVM has a different set of computational trade-offs compared to the standard computational model. In practice, this means that the price for opcodes is different to Ethereum. Also, zkEVM contains a different set of opcodes under the hood and so the “gas” metric of the same set of operations may be different on zkSync Era and on Ethereum.
+
+:::warning
+Our fee model is being constantly improved and so it is highly recommended **NOT** to hardcode any constants since the fee model changes in the future might be breaking for this constant.
+:::
+
+## `gasPerPubdataByte` should be taken into account in development
+
+Due to the state diff-based fee model of zkSync Era, every transaction includes a constant called `gasPerPubdataByte`.
+
+Presently, the operator has control over this value. However, in EIP712 transactions, users also sign an upper bound
+on this value, but the operator is free to choose any value up to that upper bound. Note, that even if the value
+is chosen by the protocol, it still fluctuates based on the L1 gas price. Therefore, relying solely on gas is inadequate.
+
+A notable example is a Gnosis Safe’s `execTransaction` method:
+
+```solidity
+// We require some gas to emit the events (at least 2500) after the execution and some to perform code until the execution (500)
+// We also include the 1/64 in the check that is not send along with a call to counteract potential shortings because of EIP-150
+require(gasleft() >= ((safeTxGas * 64) / 63).max(safeTxGas + 2500) + 500, "GS010");
+// Use scope here to limit variable lifetime and prevent `stack too deep` errors
+{
+    uint256 gasUsed = gasleft();
+    // If the gasPrice is 0 we assume that nearly all available gas can be used (it is always more than safeTxGas)
+    // We only substract 2500 (compared to the 3000 before) to ensure that the amount passed is still higher than safeTxGas
+    success = execute(to, value, data, operation, gasPrice == 0 ? (gasleft() - 2500) : safeTxGas);
+    gasUsed = gasUsed.sub(gasleft());
+
+    // ...
+}
+```
+
+While the contract does enforce the correct `gasleft()`, it does not enforce the correct `gasPerPubdata`, since there
+was no such parameter on Ethereum. This means that a malicious user could call this wallet when the `gasPerPubdata` is
+high and make the transaction fail, hence making it spend artificially more gas than required.
+
+This is the case for all relayer-like logic ported directly from Ethereum and so if you see your code relying on logic
+like “the user should provide at X gas”, then the `gasPerPubdata` should be also taken into account on zkSync Era.
+
+For now, zkSync Era operators use honest values for ETH L1 price and `gasPerPubdata`, so it should not be an issue if
+enough margin is added to the estimated gas. In order to prepare for the future decentralization of zkSync Era,
+it is imperative that you update your contract.
+
+## Use native account abstraction over `ecrecover` for validation
+
+Use zkSync Era's native account abstraction support for signature validation instead of this function.
+
+We recommend not relying on the fact that an account has an ECDSA private key, since the account may be governed by
+multisig and use another signature scheme.
+
+Read more about [zkSync Era Account Abstraction support](../../reference/concepts/aa.md).
+
+## Use local testing environment
+
+For optimal development and testing of your contracts, it is highly recommended to perform local testing before deploying them to the mainnet. Local testing allows you to test your contracts in a controlled environment, providing benefits such as reduced network latency and cost.
+
+The zkSync team provides a dockerized local setup specifically designed for local testing purposes. This setup allows you to simulate the zkSync network locally, enabling you to validate your contracts effectively.
+
+By incorporating local testing into your development workflow, you can effectively verify the behavior and functionality of your contracts in a controlled environment, ensuring a smooth deployment process to the mainnet.
+
+For detailed instructions on configuring the local testing environment and performing tests using Mocha and Chai, refer to the dedicated [Local Testing](../../tools/hardhat/testing.md) page.
diff --git a/docs/dev/building-on-zksync/hello-world.md b/docs/dev/building-on-zksync/hello-world.md
@@ -716,5 +716,6 @@ After the transaction is processed, the page updates the balances and the new gr
 
 ### Learn more
 
+- For an overview of best practices and recommendations for developing on zkSync Era, refer to the [Best Practices and Considerations](./best-practices.md) section.
 - To learn more about `zksync-web3` SDK, check out its [documentation](../../api/js).
 - To learn more about the zkSync hardhat plugins, check out their [documentation](../../tools/hardhat).
diff --git a/docs/dev/building-on-zksync/interacting.md b/docs/dev/building-on-zksync/interacting.md
@@ -1,8 +1,4 @@
-# Interact with zkSync Era :skull_and_crossbones:
-
-:::danger
-This page is under construction and may be out-of-date.
-:::
+# Interact with zkSync Era
 
 ## Do I need experience with zkSync Lite?
 
@@ -16,6 +12,8 @@ The only other place where using zkSync SDK is required is during contract deplo
 
 ### Quickstart on zkSync
 
+Before diving into the technical details, we highly recommend checking out our [Best Practices and Considerations](./best-practices.md) and [Differenes with Ethereum](../../reference/architecture/differences-with-ethereum.md) sections. This will help align your development with the distinctive attributes of zkSync Era and ensure your projects are secure and optimized.
+
 Check out our step-by-step [quickstart guide](../building-on-zksync/hello-world.md), where you will learn:
 
 - How to install zkSync hardhat plugin and deploy smart contracts with it.
@@ -55,64 +53,3 @@ In order to add the zkSync Era alpha mainnet network to your wallet, you will ne
 - WebSocket URL: `wss://testnet.era.zksync.dev/ws`
 
 5. Click "Save"
-
-## zkSync Era Support
-
-You can open a support ticket in `💻🧪│dev-support-beta` or ask any questions in `🖥│dev-general`
-
-If you need help with anything related to the zkSync Era, you can raise a support ticket on the zkSync Era discord, or check out the [FAQs](../../reference/troubleshooting/faq.md) page to view the most common queries about the zkSync Era. Additionally, you can reach out to the support team available on the `#dev-support-beta`, or ask any questions in `#dev-general` channel on the zkSync Era Discord server. 
-Instructions for raising a support ticket are as follows:
-
-- Join the zkSync Era [our Discord](https://join.zksync.dev/) server.
-- Accept the invite sent.
-- Navigate to the `#dev-support-beta` channel.
-
-Alternatively, you can now contact our support engineers with your questions and concerns via [email](mailto:[email protected]). 
-We will actively monitor for issues and work to resolve them as soon as possible.
-
-<!-- ## Deposit and withdraw funds using zkSync Portal
-
-As the testnet is running on Goerli network, you will need to get some Goerli ETH first. Try any of the faucets below.
-
-- [https://goerli-faucet.mudit.blog/](https://goerli-faucet.mudit.blog/)
-- [https://faucets.chain.link/goerli](https://faucets.chain.link/goerli)
-- [https://goerli-faucet.slock.it/](https://goerli-faucet.slock.it/)
-- [https://goerlifaucet.com/](https://goerlifaucet.com/)
-
-**Step 1**
-
-Head to [https://goerli.portal.zksync.io/](https://goerli.portal.zksync.io/) and connect your wallet. You will automatically be asked to add the “zkSync Era testnet Goerli” network.
-
-You may also add the network manually to your metamask.
-
-- Network Name: `zkSync mainnet`
-- New RPC URL: `https://zksync2-mainnet.zksync.io`
-- Chain ID: `324` -->
-<!-- 
-**Step 2 (Skip if you don’t have Goerli ETH)**
-
-We first go to “Bridge” and then “Deposit” to deposit some \$ETH to zkSync Era.
-
-![image](../../assets/images/faq-1.png)
-
-**Step 3**
-
-Next, we go to “Faucet” to get some testnet $ETH, $LINK, $DAI, $WBTC and \$USDC into our zkSync address.
-
-![image](../../assets/images/faq-2.png)
-
-Check your balance at “Balances” after claiming.
-
-![image](../../assets/images/faq-3.png)
-
-**Step 4**
-
-Now go to “Transfer”. Input the address of another wallet and transfer some tokens to it. Pay the fees in DAI if you don’t have ETH.
-
-![image](../../assets/images/faq-4.png)
-
-**Step 5**
-
-At last we go to “Withdraw” to withdraw some \$DAI from zkSync back to Goerli. Pay the fees in ETH.
-
-![image](../../assets/images/faq-5.png) -->
diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -1,12 +1,35 @@
 # Technical reference
 
-This section of the docs contains zkSync Era conceptual, architecture, and troubleshooting information.
+This section of our documentation provides comprehensive information on the concepts, architecture, and troubleshooting aspects of zkSync Era.
 
-:::danger
-- This section of the docs is under construction.
-- You may come across erroneous information in this section.
-- A doc gets a :star: if we have completed a full review on it.
-:::
+## Concepts
 
+- [Intro to rollups](./concepts/rollups.md): Gain a foundational understanding of rollups.
+- [zkSync Era basics](./concepts/zkSync.md): Explore the fundamental concepts of the zkSync Era.
+- [Hyperscaling](./concepts/hyperscaling.md): Delve into the mechanisms and impacts of hyperscaling.
+- [Transactions](./concepts/transactions/transactions.md): Learn about the transactions within zkSync Era.
+- [Blocks](./concepts/transactions/blocks.md): Understand the role and structure of blocks in zkSync Era. 
+- [Fee mechanism](./concepts/transactions/fee-model.md): Discover how the system handles transaction fees.
+- [Finality](./concepts/finality.md): Learn about finality on zkSync Era. 
+- [Account abstraction support](./concepts/aa.md): Discover the benefits and applications of account abstraction.
+- [Bridging assets](./concepts/bridging-asset.md): Learn about the mechanisms for bridging assets.
+- [L1 / L2 interoperability](./concepts/l1-l2-interop.md): Understand the interactions and compatibility between L1 and L2.
+- [Videos](./concepts/videos.md): Access visual learning resources about zkSync Era.
 
+## Architecture
 
+- [Differences with Ethereum](./architecture/differences-with-ethereum.md): Compare and contrast the current system's architecture with that of Ethereum.
+- [Smart contract development](./architecture/contracts/contract-development.md): Explore the tools and languages supported on zkSync Era for contract development. 
+- [Contract deployment](./architecture/contracts/contract-deployment.md): Understand how to successfully deploy smart contracts.
+- [System contracts](./architecture/contracts/system-contracts.md): Learn about the system-level contracts and their roles.
+- [Handling events](./architecture/events.md): Discover how the system processes and reacts to events.
+
+## Troubleshooting
+
+- [Important links](./troubleshooting/important-links.md): Access key resources for troubleshooting.
+- [Changelog](./troubleshooting/changelog.md): Stay up-to-date with the latest changes and updates.
+- [Withdrawal delay](./troubleshooting/withdrawal-delay.md): Understand the safety mechanisms in place and an explanation on the block execution delay in zkSync.
+- [Audits and bug bounty program](./troubleshooting/audit-bug-bounty.md): Learn about the system's security measures and how to participate in the bug bounty program.
+- [Contribute to documentation](./troubleshooting/docs-contribution/docs.md): Get involved in enhancing and expanding the project's documentation.
+- [Community resources](./troubleshooting/docs-contribution/community-resources.md): Access resources created by the community for the community.
+- [FAQ](./troubleshooting/faq.md): Find answers to common questions about zkSync Era and its features.