Cleanup docs

.github/workflows/linter.yml

@@ -24,4 +24,4 @@ jobs:
             # in subdirectories. The former only checks sol files in the current directory and directories one level down.
             - name: Run Lint
               run: |
-                  ./scripts/local/lint.sh
+                  ./scripts/lint.sh

README.md

@@ -1,26 +1,26 @@
-# Overview
+## Overview
 
 Teleporter is an EVM compatible cross-subnet communication protocol built on top of [Avalanche Warp Messaging (AWM)](https://docs.avax.network/learn/avalanche/awm), and implemented as a Solidity smart contract. It provides a mechanism to asynchronously invoke smart contract functions on other EVM blockchains within Avalanche. Teleporter provides a handful of useful features on top of AWM, such as specifying relayer incentives for message delivery, replay protection, message delivery and execution retries, and a standard interface for sending and receiving messages within a dApp deployed across multiple subnets.
 
 It's important to understand the distinction between Avalanche Warp Messaging and Teleporter. AWM allows subnets to communicate with each other via authenticated messages by providing signing and verification primitives in Avalanchego. These are used by the blockchain VMs to sign outgoing messages and verify incoming messages.
 
-The Teleporter protocol, on the other hand, is implemented at the smart contract level, and is a user-friendly interface to AWM, aimed at dApp developers. All of the message signing and verification is abstracted away from developers. Instead, developers simply call `sendCrossChainMessage` on the `TeleporterMessenger` contract to send a message invoking a smart contract on another subnet, and implement the `ITeleporterReceiver` interface to receive messages on the destination subnet. Teleporter handles all of the message signing and verification, as well as the message delivery and execution.
-
-**Note:** Teleporter and Avalanche Warp Messaging are under active development and may cease to function at any time. This repository is intended to be used for testing and development purposes only and should **not** be used in production.
+The Teleporter protocol, on the other hand, is implemented at the smart contract level, and is a user-friendly interface to AWM, aimed at dApp developers. All of the message signing and verification is abstracted away from developers. Instead, developers simply call `sendCrossChainMessage` on the `TeleporterMessenger` contract to send a message invoking a smart contract on another subnet, and implement the `ITeleporterReceiver` interface to receive messages on the destination subnet. Teleporter handles all of the Warp message construction and sending, as well as the message delivery and execution.
 
 - [Overview](#overview)
-  - [Setup](#setup)
-    - [Docker Setup](#docker-setup)
-    - [General Setup](#general-setup)
-  - [Structure](#structure)
-  - [Build + Run + Test](#build--run--test)
-    - [Run tests on Fuji Testnet](#run-tests-on-fuji-testnet)
-    - [E2E tests](#e2e-tests)
-  - [Docs](#docs)
-  - [Resources](#resources)
+- [Setup](#setup)
+  - [Docker Setup](#docker-setup)
+  - [General Setup](#general-setup)
+- [Structure](#structure)
+- [Build + Run + Test](#build--run--test)
+  - [Run tests on Fuji Testnet](#run-tests-on-fuji-testnet)
+  - [E2E tests](#e2e-tests)
+- [Docs](#docs)
+- [Resources](#resources)
 
 ## Setup
+
 ### Docker Setup
+
 - Install Docker:
 
 ```
@@ -57,28 +57,36 @@ docker run hello-world # This should work without sudo now
 - Note that as you develop and continuously build Docker images, it will eat up continuously more disk space. Periodically you'll want to remedy this be removing everything Docker has built: `docker system prune --all --volumes --force`
 
 ### General Setup
+
 The above steps are sufficient to run the included integration tests inside Docker containers. If you wish to run them outside docker, you'll need to install the following dependencies:
 - [Foundry](https://book.getfoundry.sh/getting-started/installation)
 - [Python3](https://www.python.org/downloads/)
 
 ## Structure
 
+- `contracts/` is a [Foundry](https://github.com/foundry-rs/foundry) project that includes the implementation of the `TeleporterMessenger` contract and example dApps that demonstrate how to write contracts that interact with Teleporter.
+- `abi-bindings/` includes Go ABI bindings for the contracts in `contracts/`.
+- `tests/` includes integration tests for the contracts in `contracts/`, written using the [Ginkgo](https://onsi.github.io/ginkgo/) testing framework
+- `utils/` includes Go utility functions for interacting with the contracts in `contracts/`. Included are Golang scripts to derive the expected EVM contract address deployed from a given EOA at a specific nonce, and also construct a transaction to deploy provided byte code to the same address on any EVM chain using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#).
 - `subnet-evm/` is the public subnet-evm repository (included as a submodule) checked out on the `warp-contract` branch with our changes.
-- `contract-deployment/` includes Golang scripts to derive the expected EVM contract address deployed from a given EOA at a specific nonce, and also construct a transaction to deploy provided byte code to the same address on any EVM chain using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#).
-- `contracts/` is a [foundry](https://github.com/foundry-rs/foundry) project that includes the implementation of the `TeleporterMessenger` contract and other dApps that serve as examples for how to write contracts that interact with Teleporter.
-- `scripts/` includes scripts to run Teleporter and integration tests.
-  - Note that all the scripts should be run from the root of the repository.
-  - `scripts/local/` includes scripts to run Teleporter in Docker containers and tests in the `scripts/local/integration-tests` locally.
+- `scripts/` includes bash scripts for interacting with Teleporter in various environments, as well as utility scripts. All the scripts should be run from the root of the repository.
+  - `abi_bindings.sh` generates ABI bindings for the contracts in `contracts/` and outputs them to `abi-bindings/`
+  - `lint.sh` lints the contracts in `contracts/`
+  - `scripts/local/` includes scripts for running Teleporter in Docker containers and tests in the `scripts/local/integration-tests` locally.
     - `scripts/local/integration-tests/` includes integration test scripts written in bash. The scripts use `foundry` to deploy smart contracts that use Teleporter, send transactions to interact with the contracts, and check that cross-chain messages have the expected effect on destination chains.
-  - `scripts/fuji/` includes scripts to interact with a live Teleporter deployment on Fuji subnets.
-    - `scripts/fuji/example-workflows/` includes example workflows that send transactions to interact with Teleporter contracts on Fuji subnets.
-- `docker/` includes containerized setup for running a local setup of Teleporter, as well as a script to run each of the integration tests against the local network.
+      - *Note* These tests will be deprecated in favor of the end to end tests in `tests/`, written using the [Ginkgo](https://onsi.github.io/ginkgo/) testing framework
+    - `scripts/fuji/` includes scripts to interact with a live Teleporter deployment on Fuji subnets.
+      - `scripts/fuji/example-workflows/` includes example workflows that send transactions to interact with Teleporter contracts on Fuji subnets.
+- `docker/` includes a containerized setup for running a local setup of Teleporter
 
-## Build + Run + Test
+## Run the Docker integration tests
 
 - Get all submodules: `git submodule update --init --recursive`
 - Install Docker as described in the setup section of the README in the root of this repository.
-- If we are using a local version of the `awm-relayer` image, build it using `./scripts/build_local_image.sh` from the root of `awm-relayer` repository.
+- If we are using a local version of the `awm-relayer` image, build it using `./scripts/build_local_image.sh` from the root of the `awm-relayer` repository.
+
+### Start up the local testnet
+
 - Run `./scripts/local/run.sh` to run the local testnet in Docker containers with the ability to interact with the nodes directly.
   - `./scripts/local/run.sh` usage is as follows:
   ```
@@ -93,7 +101,7 @@ cast send --private-key 0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5c
 cast balance --rpc-url http://127.0.0.1:9652/ext/bc/C/rpc 0x333d17d3b42bf7930dbc6e852ca7bcf560a69003
 ```
 
-- After calling `./scripts/local/run.sh`, you can directly send messages between the deployed subnets (in comparison, calling `./scripts/local/test.sh` runs the same setup steps, then runs the tests in `./scripts/integration-tests/` automatically). As an example, `./scripts/integration-tests/basic_send_receive.sh` can be run manually like so:
+- After calling `./scripts/local/run.sh`, you can directly send messages between the deployed subnets . As an example, `./scripts/integration-tests/basic_send_receive.sh` can be run manually like so:
 
 ```
 # Open a shell in the container
@@ -121,13 +129,29 @@ source vars.sh
   ./run_stop.sh             # stop the running containers and preserve the network for subsequent runs
   ./run_stop.sh -c          # stop the running containers and clean the network
   ```
-- Additional Notes:
-  - Both the `./scripts/local/run.sh` and `./scripts/local/test.sh` scripts run local five node networks, with each of the nodes validating the primary network and three subnets (Subnet A, Subnet B, and Subnet C).
-  - Logs from the subnets on one of the five nodes are printed to stdout when run using either script.
-  - These logs can also be found at `~/.avalanche-cli/runs/network-runner-root-data_<DATE>_<TIMESTAMP>/node{1,5]/logs/<SUBNET_ID>.log`, or at `/var/lib/docker/overlay2/<CONTAINER_ID>/merged/root/.avalanche-cli/....` on your local machine. You will need to be the root user to access the logs under `/var/lib`.
+
+### Run the integration tests in Docker containers
+
+- Run `./scripts/local/test.sh` to run the integration tests in Docker containers.
+  - `./scripts/local/test.sh` usage is as follows:
+  ```
+    -t, --test <test_name>            Run a specific test. If empty, runs all tests in the ./scripts/local/integration-tests/
+    -t, --test "test1 test2"          Run multiple tests. Test names must be space delimited and enclosed in quotes
+    -l, --local-relayer-image <tag>   Use a local AWM Relayer image instead of pulling from dockerhub
+    -h, --help                        Print this help message
+  ```
+  - Note that if `-l, --local` is not set, then the latest published `awm-relayer` image will be pulled from Dockerhub.
+- This script performs the same setup steps as `scripts/local/run.sh` (described above), and then runs the tests in `./scripts/integration-tests/` automatically
+
+### Additional notes
+
+- Both the `./scripts/local/run.sh` and `./scripts/local/test.sh` scripts run local five node networks, with each of the nodes validating the primary network and three subnets (Subnet A, Subnet B, and Subnet C).
+- Logs from the subnets on one of the five nodes are printed to stdout when run using either script.
+- These logs can also be found at `~/.avalanche-cli/runs/network-runner-root-data_<DATE>_<TIMESTAMP>/node{1,5]/logs/<SUBNET_ID>.log`, or at `/var/lib/docker/overlay2/<CONTAINER_ID>/merged/root/.avalanche-cli/....` on your local machine. You will need to be the root user to access the logs under `/var/lib`.
 
 ### Run tests on Fuji Testnet
-The following steps will allow you to run integration tests and example workflows against three Fuji subnets that have AWM enabled. These workflows send transaction on each of these subnets, so you will need to fund your account with some native tokens to pay for gas fees. The three subnets are called [Amplify](https://subnets-test.avax.network/amplify), [Bulletin](https://subnets-test.avax.network/bulletin), and [Conduit](https://subnets-test.avax.network/conduit).
+
+The following steps will allow you to run the integration tests described above and example workflows against three Fuji subnets that have AWM enabled. These workflows send transaction on each of these subnets, so you will need to fund your account with some native tokens to pay for gas fees. The three subnets are called [Amplify](https://subnets-test.avax.network/amplify), [Bulletin](https://subnets-test.avax.network/bulletin), and [Conduit](https://subnets-test.avax.network/conduit).
 
 The configuration for all the subnets is in `.env.testnet`. If needed, you can change the subnet IDs, the chain IDs, urls and teleporter contract address to match your setup.
 
@@ -160,7 +184,7 @@ source .env.testnet
 source .env
 ```
 
-### E2E tests
+## E2E tests
 
 E2E tests are ran as part of CI, but can also be ran locally with the `--local` flag. To run the E2E tests locally, you'll need to install Gingko following the intructions [here](https://onsi.github.io/ginkgo/#installing-ginkgo)
 
@@ -169,7 +193,7 @@ Next, provide the path to the `subnet-evm` repository and the path to a writeabl
 ./scripts/local/e2e_test.sh --local --subnet-evm ./subnet-evm --data-dir ~/tmp/e2e-test
 ```
 
-### ABI Bindings
+## ABI Bindings
 
 To generate Golang ABI bindings for the Solidity smart contracts, run:
 ```bash

contracts/src/CrossChainApplications/ERC20Bridge/README.md

@@ -13,7 +13,7 @@ The generic ERC20 bridge is implemented using two primary contracts.
     - Bridge contract that uses Teleporter to facilitate the bridging operations of adding new supported tokens and moving tokens between chains.
     - The bridge contract tracks the balances of each token sent to other bridge instances, and only allows those bridge instances to redeem up to the amount of tokens that has been previously sent to them.
     - Primary functions include:
-        - `submitCreateBridgeToken`: Called on the origin subnet to add support for an ERC20 native to the chain to a bridge instance on a different chain. Submits a Teleporter message that invokes `createBridgeToken` on the destination chain.
+        - `submitCreateBridgeToken`: Called on the origin chain to add support for an ERC20 native to the chain to a bridge instance on a different chain. Submits a Teleporter message that invokes `createBridgeToken` on the destination chain.
         - `createBridgeToken`: Called by cross-chain messages to add support for a new bridge token from another chain. Assuming the token is not already supported, deploys a new `BridgeToken` contract instance to represent the tokens on this chain.
         - `bridgeTokens`: Called to move supported tokens from one chain to another. This includes both "wrapping" of tokens native to the chain and also "unwrapping" of bridge tokens on the chain to other chains. In the case of unwrapping or moving of a bridge token, if the destination chain ID is the native chain for the given token, the original token is sent to the recipient on the destination. If the destination chain ID is another non-native chain for the underlying token, a Teleporter message is first sent to the native chain, which then subsequently updates its accounting of balances and sends a Teleporter message on the destination chain to re-wrap the given tokens. This multi-hop flow is illustrated below.
         - `mintBridgeTokens`: Called by cross-chain messages in the event of new bridge transfers of tokens from their native chains.
@@ -25,7 +25,7 @@ The generic ERC20 bridge is implemented using two primary contracts.
 </div>
 
 ## Integration Test
-An integration test demostrating the use of the generic ERC20 token bridge contracts can be found from the root of this repository in `integration-tests/erc20_bridge_multihop.sh`. This test implements the following flow and checks that each step is successful:
+An integration test demostrating the use of the generic ERC20 token bridge contracts can be found from the root of this repository in `scripts/local/integration-tests/erc20_bridge_multihop.sh`. This test implements the following flow and checks that each step is successful:
 1. An example "native" ERC20 token is deployed on subnet A
 1. The `ERC20Bridge` contract is deployed on subnets A, B, and C.
 1. Teleporter messages are sent from subnet A to B and subnet A to C to add the example ERC20 deployed in step 1 to the bridge instances on the other chains.