From bff1706261a8188e7660a9bb866be4401491ccf6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A1n=20Jakub=20Nani=C5=A1ta?= Date: Wed, 3 Jan 2024 09:50:13 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=B9=20Clean=20up=20docs=20&=20README?= =?UTF-8?q?=20(#143)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHEATSHEET.md | 32 +++++---- DEVELOPMENT.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 180 ++++------------------------------------------- 3 files changed, 218 insertions(+), 181 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/CHEATSHEET.md b/CHEATSHEET.md index 14db9a2bc..0553d9f19 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -4,29 +4,33 @@

+

+ Homepage | Docs | Developers +

+

Developer Cheatsheet

## Glossary -| Name | Package | Meaning | -| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `OmniPoint` | `utils` | Location of a contract/program in omnichain environment. Consists of an `address` and `EndpointId` | -| `OmniVector` | `utils` | Directional connection between two `OmniPoint`s. Consists of `from` and `to` `OmniPoint`s | -| `OmniNode` | `utils` | Combination of an `OmniPoint` and an arbitrary configuration attached to it. Consists of a `point` and `config` | -| `OmniEdge` | `utils` | Combination of an `OmniVector` and an arbitrary configuration attached to it. Consists of a `vector` and `config` | -| `OmniGraph` | `utils` | Collection of `OmniNode`s and `OmniEdge`s that together represent a state of an omnichain application. Consists of `contracts` and `connections` | -| `OmniError` | `utils` | Wraps an arbitrary `error` object to add information about where that error happened. Consists of `error` and `point` | -| `OmniContract` | `utils-evm` | Wraps an `ethers` `Contract` instance to add information about the endpoint. Consists of `eid` and `contract` | -| `OmniPointHardhat` | `utils-evm-hardhat` | Hardhat-specific variation of `OmniPoint`. Since in hardhat we can get a contract address by its name (from `deployments`), this version of `OmniPoint` allows us to use `contractName` instead of `address` | +| Name | Package | Meaning | +| ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `OmniPoint` | `@layerzerolabs/devtools` | Location of a contract/program in omnichain environment. Consists of an `address` and `EndpointId` | +| `OmniVector` | `@layerzerolabs/devtools` | Directional connection between two `OmniPoint`s. Consists of `from` and `to` `OmniPoint`s | +| `OmniNode` | `@layerzerolabs/devtools` | Combination of an `OmniPoint` and an arbitrary configuration attached to it. Consists of a `point` and `config` | +| `OmniEdge` | `@layerzerolabs/devtools` | Combination of an `OmniVector` and an arbitrary configuration attached to it. Consists of a `vector` and `config` | +| `OmniGraph` | `@layerzerolabs/devtools` | Collection of `OmniNode`s and `OmniEdge`s that together represent a state of an omnichain application. Consists of `contracts` and `connections` | +| `OmniError` | `@layerzerolabs/devtools` | Wraps an arbitrary `error` object to add information about where that error happened. Consists of `error` and `point` | +| `OmniContract` | `@layerzerolabs/devtools-evm` | Wraps an `ethers` `Contract` instance to add information about the endpoint. Consists of `eid` and `contract` | +| `OmniPointHardhat` | `@layerzerolabs/devtools-evm-hardhat` | Hardhat-specific variation of `OmniPoint`. Since in hardhat we can get a contract address by its name (from `deployments`), this version of `OmniPoint` allows us to use `contractName` instead of `address` | ## Conventions The packages are laid out according to the [principle of least knowledge](https://en.wikipedia.org/wiki/Law_of_Demeter). Their domain of action is also reflected in their name that follows the convention `[DOMAIN-][-MODIFIER]`, for example: -- `utils` package is the most generic package and it itself does not know and cannot use any implementation details of any more specific packages, nor is it specific to any domain -- `utils-evm` package is specific to the `EVM` implementaion but it is not specific to any domain -- `ua-utils-evm` package is specific to the `EVM` implementation and specific to the `ua` (user application) domain -- `ua-utils-evm-hardhat` package is specific to the `EVM` implementation using `hardhat` and specific to the `ua` (user application) domain +- `@layerzerolabs/devtools` package is the most generic package and it itself does not know and cannot use any implementation details of any more specific packages, nor is it specific to any domain +- `@layerzerolabs/devtools-evm` package is specific to the `EVM` implementaion but it is not specific to any domain +- `@layerzerolabs/ua-devtools-evm` package is specific to the `EVM` implementation and specific to the `ua` (user application) domain +- `@layerzerolabs/ua-devtools-evm-hardhat` package is specific to the `EVM` implementation using `hardhat` and specific to the `ua` (user application) domain The only exceptions to this rule are packages that need to follow an existing naming convention (`create-lz-oapp`) or packages for which the name needs to appeal or be intuitive/familiar to the user (`toolbox-hardhat`) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..d1b2e7f68 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,187 @@ +

+ + LayerZero + +

+ +

+ Homepage | Docs | Developers +

+ +

Development

+ +## Code layout + +The code is arranged into: + +- **Reusable packages** under `./packages` directory +- **Example projects** under `./examples` directory +- **Test projects & helpers** under `./tests` directory + +## Development + +```bash +# or nvm install if nvm use fails +nvm use + +yarn + +# Build the entire project +yarn build + +# Lints the entire project +yarn lint + +# Tests the entire project +yarn test + +# Runs the project in development mode +yarn dev +``` + +This project is built using `turborepo`. The above commands are just aliases to `turbo` CLI and as such support all the `turbo` options: + +```bash +# To start the development mode for create-lz-oapp and its dependencies +yarn dev --filter=create-lz-oapp... +``` + +### Running tests + +The tests are by default executed in a containerized environment that sets up two `hardhat` nodes accessible from within the environment: + +- `http://network-britney:8545` +- `http://network-vengaboys:8545` + +You can run the whole test suite within this environment by running: + +```bash +yarn test +``` + +#### Refining tested packages + +To only run a specific test suite, you can define `DOCKER_COMPOSE_RUN_TESTS_TURBO_ARGS` environment variable before running the tests. This variable will be passed to the underlying `turbo` command and can contain any arguments that this command understands, for example: + +```bash +# To only run tests for @layerzerolabs/ua-devtools-evm-hardhat-test package +DOCKER_COMPOSE_RUN_TESTS_TURBO_ARGS=--filter=ua-devtools-evm-hardhat-test yarn test +``` + +#### Rebuilding containers + +`docker compose` will by default reuse images for containers it has already built. If by any chance you are seeing code changes not being reflected in your test runs, you can force docker to rebuild the images by defining `DOCKER_COMPOSE_RUN_TESTS_ARGS` environment variable. This variable will be passed to the underlying `docker compose run` command and can contain any arguments that this command understands, for example: + +```bash +DOCKER_COMPOSE_RUN_TESTS_ARGS=--build yarn test +``` + +You also combine the environment variables: + +```bash +DOCKER_COMPOSE_RUN_TESTS_TURBO_ARGS=--filter=ua-devtools-evm-hardhat-test DOCKER_COMPOSE_RUN_TESTS_ARGS=--build yarn test +``` + +#### Container logs + +To monitor the container logs you'll need to run: + +```bash +docker compose logs -f +``` + +This allows you to monitor logs coming from e.g. the `hardhat` nodes + +#### Exposing test networks on `localhost` + +It is possible to expose the test networks defined in `docker-compose.yaml` on your host machine. To do this, you can run: + +```bash +yarn start +``` + +Once the networks are running, you can go to the `ua-devtools-evm-hardhat-test` package: + +```bash +cd packages/ua-devtools-hardhat-test +``` + +Setup the default `EndpointV2` and `DefaultOApp`: + +```bash +npx hardhat lz:test:oapp:deploy +``` + +And execute `hardhat` tasks as usual: + +```bash +npx hardhat lz:oapp:getDefaultConfig +``` + +If you are developing tasks, it's useful to build the code when it changes. To do this, run the following from the project root: + +```bash +yarn dev +``` + +To stop the network containers, just run: + +```bash +yarn stop +``` + +**Don't forget that the state of the local networks disappears after they are stopped and any deployment files created in one session will be invalid in the next one.** + +### Troubleshooting + +#### Problems with committing + +If facing issues when committing, make sure your `~/.huskyrc` file contains the following: + +```bash +# This loads nvm.sh and sets the correct PATH before running hook +export NVM_DIR="$HOME/.nvm" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" +``` + +#### Problems with package updating + +To update external `@layerzerolabs` packages, you can use the builtin `yarn` utility: + +```bash +yarn upgrade-interactive --scope @layerzerolabs --latest +``` + +However, this utility has an issue with packages that are listed both at the workspace root and in the individual packages, e.g. `@layerzerolabs/prettier-config-next` - it errors out saying that a workspace package could not be found. + +To work around this (since this version of yarn is outdated and a fix for this problem will not be provided), you can remove the entries from the root `package.json` before running the command, then add them back (just don't forget to update their versions). + +#### Problems using the `dev` script + +`turbo` might complain about concurrency issues when running `yarn dev`: + +```diff +- error preparing engine: Invalid persistent task configuration: +- You have 18 persistent tasks but `turbo` is configured for concurrency of 10. Set --concurrency to at least 19 +``` + +If you see this error, just follow turbo's lead and use: + +```bash +yarn dev --concurrency 19 +``` + +#### Problems with snapshots + +We use jest snapshots in a lot of places throughout the codebase. When an intentional change to the codebase is made and snapshots need to be updated, there are several ways of doing so: + +- Erase the original snapshot file and run the test. The snapshot will be recreated and the diff should only show your expected changes +- Run the tests from within the affected package with `-u` flag. This will update the snapshots. + +For some packages the snapshot output depends on environment variables and other factors. For example the `io-devtools` tests for printers have different output based on whether the active shell is`TTY` orwhether the `CI` environment variable is set and non-empty. + +If you encounter errors when running these tests, just set the environment variable before running the test: + +```bash +CI=1 yarn test +``` diff --git a/README.md b/README.md index fdc9d1dbe..d039b33b1 100644 --- a/README.md +++ b/README.md @@ -4,180 +4,26 @@

-

LayerZero Developer Utilities

- -## Code layout - -The code is arranged into: - -- **Reusable packages** under `./packages` directory -- **Example projects** under `./examples` directory -- **Test projects & helpers** under `./tests` directory - -## Development - -```bash -# or nvm install if nvm use fails -nvm use - -yarn - -# Build the entire project -yarn build - -# Lints the entire project -yarn lint - -# Tests the entire project -yarn test - -# Runs the project in development mode -yarn dev -``` - -This project is built using `turborepo`. The above commands are just aliases to `turbo` CLI and as such support all the `turbo` options: - -```bash -# To start the development mode for create-lz-oapp and its dependencies -yarn dev --filter=create-lz-oapp... -``` - -### Running tests - -The tests are by default executed in a containerized environment that sets up two `hardhat` nodes accessible from within the environment: - -- `http://network-britney:8545` -- `http://network-vengaboys:8545` - -You can run the whole test suite within this environment by running: - -```bash -yarn test -``` - -#### Refining tested packages - -To only run a specific test suite, you can define `DOCKER_COMPOSE_RUN_TESTS_TURBO_ARGS` environment variable before running the tests. This variable will be passed to the underlying `turbo` command and can contain any arguments that this command understands, for example: - -```bash -# To only run tests for @layerzerolabs/ua-devtools-evm-hardhat-test package -DOCKER_COMPOSE_RUN_TESTS_TURBO_ARGS=--filter=ua-devtools-evm-hardhat-test yarn test -``` - -#### Rebuilding containers - -`docker compose` will by default reuse images for containers it has already built. If by any chance you are seeing code changes not being reflected in your test runs, you can force docker to rebuild the images by defining `DOCKER_COMPOSE_RUN_TESTS_ARGS` environment variable. This variable will be passed to the underlying `docker compose run` command and can contain any arguments that this command understands, for example: - -```bash -DOCKER_COMPOSE_RUN_TESTS_ARGS=--build yarn test -``` - -You also combine the environment variables: - -```bash -DOCKER_COMPOSE_RUN_TESTS_TURBO_ARGS=--filter=ua-devtools-evm-hardhat-test DOCKER_COMPOSE_RUN_TESTS_ARGS=--build yarn test -``` - -#### Container logs - -To monitor the container logs you'll need to run: - -```bash -docker compose logs -f -``` - -This allows you to monitor logs coming from e.g. the `hardhat` nodes - -#### Exposing test networks on `localhost` - -It is possible to expose the test networks defined in `docker-compose.yaml` on your host machine. To do this, you can run: - -```bash -yarn start -``` - -Once the networks are running, you can go to the `ua-devtools-evm-hardhat-test` package: - -```bash -cd packages/ua-devtools-hardhat-test -``` - -Setup the default `EndpointV2` and `DefaultOApp`: - -```bash -npx hardhat lz:test:oapp:deploy -``` - -And execute `hardhat` tasks as usual: - -```bash -npx hardhat lz:oapp:getDefaultConfig -``` - -If you are developing tasks, it's useful to build the code when it changes. To do this, run the following from the project root: - -```bash -yarn dev -``` - -To stop the network containers, just run: - -```bash -yarn stop -``` - -**Don't forget that the state of the local networks disappears after they are stopped and any deployment files created in one session will be invalid in the next one.** - -### Troubleshooting - -#### Problems with committing - -If facing issues when committing, make sure your `~/.huskyrc` file contains the following: - -```bash -# This loads nvm.sh and sets the correct PATH before running hook -export NVM_DIR="$HOME/.nvm" -[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" -``` - -#### Problems with package updating - -To update external `@layerzerolabs` packages, you can use the builtin `yarn` utility: - -```bash -yarn upgrade-interactive --scope @layerzerolabs --latest -``` +

+ Homepage | Docs | Developers +

-However, this utility has an issue with packages that are listed both at the workspace root and in the individual packages, e.g. `@layerzerolabs/prettier-config-next` - it errors out saying that a workspace package could not be found. +

LayerZero Developer Utilities

-To work around this (since this version of yarn is outdated and a fix for this problem will not be provided), you can remove the entries from the root `package.json` before running the command, then add them back (just don't forget to update their versions). +

+ Development | Cheatsheet | Examples +

-#### Problems using the `dev` script +## Getting started -`turbo` might complain about concurrency issues when running `yarn dev`: +Visit our developer docs to get started with LayerZero. -```diff -- error preparing engine: Invalid persistent task configuration: -- You have 18 persistent tasks but `turbo` is configured for concurrency of 10. Set --concurrency to at least 19 -``` +## Bootstrapping an example project -If you see this error, just follow turbo's lead and use: +Start developing in no time using our `create-lz-oapp` CLI utility: ```bash -yarn dev --concurrency 19 +npx create-lz-oapp@latest ``` -#### Problems with snapshots - -We use jest snapshots in a lot of places throughout the codebase. When an intentional change to the codebase is made and snapshots need to be updated, there are several ways of doing so: - -- Erase the original snapshot file and run the test. The snapshot will be recreated and the diff should only show your expected changes -- Run the tests from within the affected package with `-u` flag. This will update the snapshots. - -For some packages the snapshot output depends on environment variables and other factors. For example the `io-devtools` tests for printers have different output based on whether the active shell is`TTY` orwhether the `CI` environment variable is set and non-empty. - -If you encounter errors when running these tests, just set the environment variable before running the test: - -```bash -CI=1 yarn test -``` +This will walk you through a project setup and will bootstrap a project based on one of the examples we provide in this repository.