Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: readme cleanup #584

Merged
merged 1 commit into from
Sep 19, 2024
Merged

docs: readme cleanup #584

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
210 changes: 20 additions & 190 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,210 +1,40 @@
## Foundry with ZKsync Era v0.2-alpha
# **Foundry with ZKsync Era - Alpha**

This repository enhances Foundry to support ZKsync, enabling Solidity-based compilation, deployment, testing, and interaction with smart contracts on ZKsync.
**[Install](https://foundry-book.zksync.io/getting-started/installation)**
| [Limitations](https://foundry-book.zksync.io/zksync-specifics/limitations/)
| [User Book](https://foundry-book.zksync.io/)
| [ZKsync Docs](https://docs.zksync.io/build/tooling/foundry/overview)

> 🔧 **Fork Notice:** This is a Foundry fork with added zkSync support.
>
> ⚠️ **Alpha Stage:** The project is in alpha, so you might encounter issues.
>
> 🐞 **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

Follow these steps to quickly install the binaries for `foundry-zksync`:

**Note:** This installation overrides any existing `forge` and `cast` binaries in `~/.foundry`. You can use `forge` without the `--zksync` flag for standard EVM chains. To revert to a previous installation, follow the instructions [here](https://book.getfoundry.sh/getting-started/installation#using-foundryup).

### 1. **Run the Installer**

Run the following `curl` command, which downloads and runs the installation script:

```bash
curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash
```

This command will download the latest `foundry-zksync` binaries (`forge` and `cast`) and set them up on your system.

### 2. **Verify the Installation** (Recommended)

After installation, it's recommended to verify that the binaries have been installed correctly. Run the following command to check the installed version:

```bash
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:

1. **Install Rust:** Use the command below to install Rust. This will also install `cargo`, Rust's package manager and build system.

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
**Foundry ZKsync** is a specialized fork of [Foundry](https://github.com/foundry-rs/foundry), tailored for ZKsync.

2. **Set Rust to Nightly Toolchain:** This project requires Rust's nightly version from September 30, 2023. Set your Rust toolchain to the appropriate nightly version using `rustup`:

```sh
# Replace `<YOUR-TARGET>` with your specific platform target, e.g., `x86_64-unknown-linux-gnu`
rustup install nightly-2023-09-30-<YOUR-TARGET>

# Example for MacOS (Apple Silicon):
rustup install nightly-2023-09-30-aarch64-apple-darwin
```

3. **MacOS Prerequisite - Install `make`:** MacOS users need to ensure `make` is installed. If not, install it using Homebrew:

```sh
brew install make
```

Then, set the path to GNU `make`:

```sh
# For x86_64 MacOs users:
# export PATH="/usr/local/opt/make/libexec/gnubin:$PATH"
export PATH="/opt/homebrew/opt/make/libexec/gnubin:$PATH"
```

Add this export line to your shell profile (`~/.bash_profile`, `~/.zshrc`, etc.) to make the change permanent.

## 💾 Installation

Each tool within our suite can be installed individually, or you can install the entire suite at once.

### Installing `forge` 🛠️

To install `forge`, execute the command below. This action will overwrite any previous `forge` installations, but the functionality remains consistent. Post-installation, `forge` will be accessible as an executable from `~/.cargo/bin`.

Run the following command:

```bash
cargo install --path ./crates/forge --profile local --force --locked
```

### Installing `cast` 📡

Similarly, to install `cast`, use the following command. Like `forge`, this will replace any existing `cast` installations without altering functionality. Once installed, `cast` becomes available as an executable in `~/.cargo/bin`.

Run the following command:

```bash
cargo install --path ./crates/cast --profile local --force --locked
```

### Installing the Entire Suite 📦

To install all the tools in the suite:

```bash
cargo build --release
```

## Configuration

### Using `foundry.toml`

Foundry is designed to be very configurable. You can configure Foundry using a file called [`foundry.toml`](./crates/config) in the root of your project, or any other parent directory. See [config package](./crates/config/README.md#all-options) for all available options.

Configuration can be arbitrarily namespaced by profiles. The default profile is named `default` (see ["Default Profile"](./crates/config/README.md#default-profile)).

You can select another profile using the `FOUNDRY_PROFILE` environment variable. You can also override parts of your configuration using `FOUNDRY_` or `DAPP_` prefixed environment variables, like `FOUNDRY_SRC`.

`forge init` creates a basic, extendable `foundry.toml` file.

To see your current configuration, run `forge config`. To see only basic options (as set with `forge init`), run `forge config --basic`. This can be used to create a new `foundry.toml` file with `forge config --basic > foundry.toml`.

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'
libs = ['lib']

[profile.default.zksync]
compile = true
fallback_oz = true
mode = '3'
```
It extends Foundry's capabilities for Ethereum app development to support ZKsync, **allowing for the compilation, deployment, testing, and interaction with smart contracts on ZKsync.**

> ⚠️ **Alpha Stage:** The project its alpha stage, indicating ongoing development and potential for future improvements.
>
> 🐞 **Found an Issue?:** Please report it to help us improve by opening an issue or submitting a pull request.

### Additional Configuration
## 📖 User Book

You can find additional setup and configurations guides in the [Foundry Book][foundry-book]:
For **detailed information, including installation instructions, usage examples, and advanced guides**, please refer to the **[Foundry ZKsync Book](https://foundry-book.zksync.io/).**

- [Setting up VSCode][vscode-setup]
- [Shell autocompletions][shell-setup]
*If you are interested in contributing to the book, please refer to the **[Foundry ZKsync Book repository](https://github.com/matter-labs/foundry-zksync-book).***

## Contributing
## 🤝 Contributing

See our [contributing guidelines](./CONTRIBUTING.md).

## Acknowledgements
## 🗣️ Acknowledgements

### Foundry

- Foundry is a clean-room rewrite of the testing framework [DappTools](https://github.com/dapphub/dapptools). None of this would have been possible without the DappHub team's work over the years.
- [Matthias Seitz](https://twitter.com/mattsse_): Created [ethers-solc] which is the backbone of our compilation pipeline, as well as countless contributions to ethers, in particular the `abigen` macros.
- [Rohit Narurkar](https://twitter.com/rohitnarurkar): Created the Rust Solidity version manager [svm-rs](https://github.com/roynalnaruto/svm-rs) which we use to auto-detect and manage multiple Solidity versions.
- [Brock Elmore](https://twitter.com/brockjelmore): For extending the VM's cheatcodes and implementing [structured call tracing](https://github.com/foundry-rs/foundry/pull/192), a critical feature for debugging smart contract calls.
- All the other [contributors](https://github.com/foundry-rs/foundry/graphs/contributors) to the [ethers-rs](https://github.com/gakonst/ethers-rs) & [foundry](https://github.com/foundry-rs/foundry) repositories and chatrooms.

### Acknowledgments - foundry-zksync
- [Moonsong Labs](https://moonsonglabs.com/): Implemented [zkSync support](./crates/zksync/), and resolved a number of different challenges to enable zkSync support.
### Foundry ZKsync
- [Moonsong Labs](https://moonsonglabs.com/): Implemented [ZKsync crates](./crates/zksync/), and resolved a number of different challenges to enable ZKsync support.

[foundry-book]: https://book.getfoundry.sh
[foundry-gha]: https://github.com/foundry-rs/foundry-toolchain
Expand Down