Skip to content

Commit

Permalink
chore: adds link to book and reorg (#582)
Browse files Browse the repository at this point in the history 
* chore: adds link to book and reorg

* fix: update typo
  • Loading branch information
@dutterbutter
dutterbutter committed Sep 18, 2024
1 parent bc065c0 commit f7806bb
Showing 1 changed file with 59 additions and 124 deletions.
183 changes: 59 additions & 124 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,14 @@
## Foundry with zkSync Era v0.2-alpha
## Foundry with ZKsync Era v0.2-alpha

This repository enhances Foundry to support zkSync Era, enabling Solidity-based compilation, deployment, testing, and interaction with smart contracts on zkSync Era.
This repository enhances Foundry to support ZKsync, enabling Solidity-based compilation, deployment, testing, and interaction with smart contracts on ZKsync.

> πŸ”§ **Fork Notice:** This is a Foundry fork with added zkSync support.
>
> ⚠️ **Alpha Stage:** The project is in alpha, so you might encounter issues. For more information, please review [Limitations](#limitations) section.
> ⚠️ **Alpha Stage:** The project is in alpha, so you might encounter issues.
>
> 🐞 **Found an Issue?** Please report it to help us improve.
### Changes Made

To use for zkSync environments, include `--zksync` when running `forge` or `vm.zkVm(true)` in tests. The modifications include:

1. **Compilation:** `solc` and `zksolc` are used for compiling. The resulting bytecodes are combined into `DualCompiledContract` and managed through `Executor` to `CheatcodeTracer`.
2. **EVM Interactions:**
- EVM calls are standard except for `address.balance` and `block.timestamp`/`block.number`, which pull data from zkSync (ZK-storage and ZK-specific context, respectively).
3. **Transaction Handling:**
- `CALL` and `CREATE` operations are captured and converted to zkSync transactions. This process includes fetching zkSync-equivalent bytecode, managing account nonces, and marking EOA appropriately to comply with zkSync requirements.
4. **Execution and State Management:**
- zkSync VM processes the transaction and returns state changes, which are applied to `journaled_state`. Results are relayed back.
5. **Logging:**
- `console.log()` outputs within zkSync VM are captured and displayed in Foundry.
- `ZK_DEBUG_RESOLVE_HASHES` and `ZK_DEBUG_SHOW_OUTPUTS` env variable may be set to `true` to display zkSync VM call logs with resolved selector hashes (requires Internet connection), and the call outputs, respectively.
6. **Fuzzing**
- Adds config option `no_zksync_reserved_addresses`. Since zkSync reserves addresses below 2^16 as system addresses, a fuzz test would've required a broad `vm.assume` and many `vm.excludeSender` calls to exclude these. This is not only cumbersome but could also trigger `proptest`'s global `max_global_rejects` failure. When this option is set to `true` the `proptest` generation itself ensures that no invalid addresses are generated, and thus need not be filtered adding up to the `max_test_rejects` count.

## πŸ“Š Features & Limitations

### Features

`Foundry-zksync` offers a set of features designed to work with zkSync Era, providing a comprehensive toolkit for smart contract deployment and interaction:
- **Fast & flexible compilation pipeline**
- Automatic Solidity compiler version detection & installation
- **Incremental compilation & caching**: Only changed files are re-compiled
- Parallel compilation
- Non-standard directory structures support (e.g. [Hardhat repos](https://twitter.com/gakonst/status/1461289225337421829))
- **Tests are written in Solidity** (like in DappTools)
- **Fast fuzz testing** with shrinking of inputs & printing of counter-examples
- **Fast remote RPC forking mode**, leveraging Rust's async infrastructure like tokio
- **Flexible debug logging**
- DappTools-style, using `DsTest`'s emitted logs
- Hardhat-style, using the popular `console.sol` contract
- **Portable (5-10MB) & easy to install** without requiring Nix or any other package manager
- **Fast CI** with the [Foundry GitHub action][foundry-gha].

- **Smart Contract Deployment**: Easily deploy smart contracts to zkSync Era mainnet, testnet, or a local test node.
- **Contract Interaction**: Call and send transactions to deployed contracts on zkSync Era testnet or local test node.
- **Solidity Testing**: Write tests in Solidity, similar to DappTools, for a familiar testing environment.
- **Fuzz Testing**: Benefit from fuzz testing, complete with shrinking of inputs and printing of counter-examples.
- **Remote RPC Forking**: Utilize remote RPC forking mode, leveraging Rust's asynchronous infrastructure like tokio.
- **Flexible Debug Logging**: Choose your debugging style:
- DappTools-style: Utilize DsTest's emitted logs for debugging.
- Hardhat-style: Leverage the popular console.sol contract.
- **Configurable Compiler Options**: Tailor compiler settings to your needs, including LLVM optimization modes.

Forge is quite fast at both compiling (leveraging [ethers-solc]) and testing.

### Limitations

While `foundry-zksync` is **alpha stage**, there are some limitations to be aware of:

- **Compile Time**: Some users may experience slower compile times.
- **Compiling Libraries**: Compiling non-inlinable libraries requires deployment and adding to configuration or the command line with the `--libraries` argument. For more information please refer to [official docs](https://docs.zksync.io/build/developer-reference/ethereum-differences/libraries).

```
libraries = [
"src/MyLibrary.sol:MyLibrary:0xfD88CeE74f7D78697775aBDAE53f9Da1559728E4"
]
```
- **Create2 Address Derivation**: There are differences in Create2 Address derivation compared to Ethereum. [Read the details](https://docs.zksync.io/build/developer-reference/ethereum-differences/evm-instructions#create-create2).
- **Contract Verification**: Currently contract verification via the `--verify` flag do not work as expected but will be added shortly.
- **Specific Foundry Features**: Currently features such as `--gas-report`, `--coverage` may not work as intended. We are actively working on providing support for these feature types.
- **Solc Compatibility**: `zksolc` requires a `solc` binary to be run as a child process. The version/path to use for each can be specified by the `zksolc` and `solc` options in `foundry.toml`. Not all `solc` versions are supported by all `zksolc` versions, compiling with a `solc` version higher than the one supported may lead to unexpected errors. [Read the docs](https://docs.zksync.io/zk-stack/components/compiler/toolchain/solidity.html#limitations) about version limitations and check the [zksolc changelog](https://github.com/matter-labs/era-compiler-solidity/blob/main/CHANGELOG.md) to see the latest supported `solc` version.
- **Windows Compatibility**: Windows is not officially supported yet. The reported issues would be investigated on a best-effort basis.

For the most effective use of our library, we recommend familiarizing yourself with these features and limitations.
> 🐞 **Found an Issue?** Please report it to help us improve by opening an issue or submitting a pull request.
>
> πŸ“š **Foundry ZKsync Book:** For detailed information, including installation instructions, usage examples, and advanced guides, please refer to the [Foundry ZKsync Book](https://foundry-book.zksync.io/).
## Quick Install

Expand Down Expand Up @@ -102,6 +36,58 @@ forge --version

This should return the installed version of `forge`, confirming that `foundry-zksync` is installed properly on your system.

## Quickstart

In an empty directory, run the following command:

```bash
forge init
```

Let's check out what forge generated for us:

```bash
$ tree . -d -L 1
.
β”œβ”€β”€ lib
β”œβ”€β”€ script
β”œβ”€β”€ src
└── test
```

#### Compiling contracts

We can build the project with `forge build --zksync`:

```bash
$ forge build --zksync
Compiling smart contracts...
Compiled Successfully
```

#### Listing missing libraries

To scan missing non-inlinable libraries, you can build the project using the `--zk-detect-missing-libraries` flag. This will give a list of the libraries that need to be deployed and their addresses
provided via the `libraries` option for the contracts to compile.
Metadata about the libraries will be saved in `.zksolc-libraries-cache/missing_library_dependencies.json`.

#### Running Tests

You can run the tests using `forge test --zksync`.

The command and its expected output are shown below:

```bash
forge test --zksync

Ran 2 tests for test/Counter.t.sol:CounterTest
[PASS] testFuzz_SetNumber(uint256) (runs: 256, ΞΌ: 8737, ~: 8737)
[PASS] test_Increment() (gas: 8702)
Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 3.57s (3.56s CPU time)

Ran 1 test suite in 3.57s (3.57s CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests)
```

## πŸ“ Development Prerequisites

Ensure you have the necessary tools and environments set up for development:
Expand Down Expand Up @@ -170,57 +156,6 @@ To install all the tools in the suite:
cargo build --release
```
## Quickstart
In an empty directory, run the following command:
```
forge init
```
Let's check out what forge generated for us:

```
$ tree . -d -L 1
.
β”œβ”€β”€ lib
β”œβ”€β”€ script
β”œβ”€β”€ src
└── test
```
#### Compiling contracts
We can build the project with `forge build --zksync`:
```
$ forge build --zksync
Compiling smart contracts...
Compiled Successfully
```
#### Listing missing libraries
To scan missing non-inlinable libraries, you can build the project using the `--zk-detect-missing-libraries-flag`. This will give a list of the libraries that need to be deployed and their addresses
provided via the `libraries` option for the contracts to compile.
Metadata about the libraries will be saved in `.zksolc-libraries-cache/missing_library_dependencies.json`.
#### Running Tests
You can run the tests using `forge test --zksync`.
The command and its expected output are shown below:
```bash
$ forge test --zksync
Ran 2 tests for test/Counter.t.sol:CounterTest
[PASS] testFuzz_SetNumber(uint256) (runs: 256, ΞΌ: 8737, ~: 8737)
[PASS] test_Increment() (gas: 8702)
Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 3.57s (3.56s CPU time)
Ran 1 test suite in 3.57s (3.57s CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests)
```

## Configuration
### Using `foundry.toml`
Expand All @@ -237,7 +172,7 @@ To see your current configuration, run `forge config`. To see only basic options
By default `forge config` shows the currently selected foundry profile and its values. It also accepts the same arguments as `forge build`. An example `foundry.toml` for zkSync with zksolc configurations may look like:
```
```bash
[profile.default]
src = 'src'
out = 'out'
Expand Down

0 comments on commit f7806bb

Please sign in to comment.