add more docs

.github/workflows/integration.yml

@@ -1,5 +1,8 @@
 name: integration
-# TODO#q: add workflow description
+# This is an integration test workflow that:
+# - spins local nitro node
+# - deploys and check every contract at `./examples` directory
+# - runs integration test suite against all contracts deployed locally
 permissions:
   contents: read
 on:
@@ -31,6 +34,7 @@ jobs:
           toolchain: 1.77.0
       - name: install cargo-stylus
         run: RUSTFLAGS="-C link-args=-rdynamic" cargo install [email protected]
+      # TODO#q: cache nitro node images and nitro-testnode sources since it is a bottleneck for the routine
       - name: setup nitro node
         run: \
           # clone nitro test node repo

integration/README.md

@@ -1,19 +1,63 @@
 # Integration Tests
-## Testing Examples Contracts
-Deploying every contract from `./examples` and running integration tests.
+## Run tests
+Deploying every contract from `./examples` directory and running integration tests.
 ### Against local nitro node
 Set up first a local nitro node according to this [guide](https://github.com/OffchainLabs/nitro-testnode/blob/release/README.md) and run this command from the project root:
 ```terminal
     ./integration/test.sh
 ```
 
 ### Against stylus dev net
-ALICE_PRIV_KEY and BOB_PRIV_KEY should be valid funded wallets.
-
+`ALICE_PRIV_KEY` and `BOB_PRIV_KEY` should be valid funded wallets.
+`RPC_URL` should contain url of the stylus testnet.
 Run this command from the project root:
 ```terminal
     ALICE_PRIV_KEY=0x... \
     BOB_PRIV_KEY=0x... \
     RPC_URL=https://stylus-testnet.arbitrum.io/rpc \
         ./integration/test.sh
+```
+## Add test for the new contract
+Assuming that contract associated crate exists at `./examples` directory 
+with the crate name `erc20-example`.
+Add ethereum contracts to `./integration/src/infrastructure` directory like:
+```rust
+abigen!(
+    Erc20Token,
+    r#"[
+        function decimals() external view returns (uint8)
+        function totalSupply() external view returns (uint256)
+        function balanceOf(address account) external view returns (uint256)
+        function transfer(address recipient, uint256 amount) external returns (bool)
+        function allowance(address owner, address spender) external view returns (uint256)
+        function approve(address spender, uint256 amount) external returns (bool)
+        function transferFrom(address sender, address recipient, uint256 amount) external returns (bool)
+        function mint(address account, uint256 amount) external
+        function burn(uint256 amount) external
+        
+        error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed)
+    ]"#
+);
+```
+Then add wrapper type for the contract:
+```rust
+pub type Erc20 = Erc20Token<HttpMiddleware>;
+
+impl Token for Erc20 {
+    const STYLUS_PROGRAM_ADDRESS: &'static str =
+        "ERC20_EXAMPLE_DEPLOYMENT_ADDRESS";
+
+    fn new(address: Address, client: Arc<HttpMiddleware>) -> Self {
+        Self::new(address, client)
+    }
+}
+```
+Function `new` should forward call to the contract factory method.
+`STYLUS_PROGRAM_ADDRESS` should have a value of formed by the template `<CRATE_NAME>_DEPLOYMENT_ADDRESS`
+where `<CRATE_NAME>` is the "SCREAMING_SNAKE_CASE" conversion of the crate name.
+`ERC20_EXAMPLE_DEPLOYMENT_ADDRESS` in this example.
+
+Tests should create new infrastructure instance like this:
+```rust
+let infra = Infrastructure::<Erc20>::new().await?;
 ```

integration/src/erc721.rs

@@ -147,3 +147,5 @@ async fn error_not_approved_nft_transfer() -> Result<()> {
         }),
     }
 }
+
+// TODO: add more tests for erc721

integration/src/infrastructure/mod.rs

@@ -66,7 +66,7 @@ pub struct Client<T: Token> {
     pub caller: T,
 }
 
-// Lets not to mention `caller` property every time we call a function.
+// Allows not to mention `caller` property every time we call a function.
 impl<T: Token> Deref for Client<T> {
     type Target = T;
 
@@ -81,7 +81,7 @@ pub trait Token {
     /// Deployed program address environment variable name for the contract.
     ///
     /// e.g can be `ERC721_EXAMPLE_DEPLOYMENT_ADDRESS`.
-    /// Formed by template <CRATE_NAME>_DEPLOYMENT_ADDRESS
+    /// Formed by the template <CRATE_NAME>_DEPLOYMENT_ADDRESS
     /// where <CRATE_NAME> is the "SCREAMING_SNAKE_CASE" conversion of the crate
     /// name from the `./examples` directory.
     /// That environment variable should store an address of the corresponding