Merge pull request #257 from getwax/update-repo-docs

Update Repo Documentation, archive older components, CI e2e tests

.github/workflows/barebones.yml

@@ -1,16 +1,16 @@
-name: packages/barebones
+name: archive/barebones
 
 on:
   push:
     branches:
       - main
   pull_request:
     paths:
-      - packages/barebones/**
+      - archive/barebones/**
 
 defaults:
   run:
-    working-directory: ./packages/barebones
+    working-directory: ./archive/barebones
 
 env:
   FOUNDRY_PROFILE: ci

.github/workflows/plugins.yml

@@ -29,28 +29,6 @@ jobs:
         with:
           version: nightly
 
-      # Uncomment the lines below to install & generate zk assets
-      # - working-directory: ./packages/zkp/lib/circom
-      #   run: cargo build --release
-
-      # - working-directory: ./packages/zkp/lib/circom
-      #   run: cargo install --path circom
-
-      # - uses: actions/setup-node@v3
-      #   with:
-      #     node-version: "18.x"
-      #     cache: "yarn"
-      #     cache-dependency-path: packages/zkp/yarn.lock
-
-      # - working-directory: ./packages/zkp
-      #   run: yarn install --frozen-lockfile
-
-      # - working-directory: ./packages/zkp
-      #   run: yarn build
-
-      # - working-directory: ./packages/plugins
-      #   run: yarn install --frozen-lockfile
-
       - name: Run Forge build
         run: |
           forge --version
@@ -81,24 +59,20 @@ jobs:
           cache: "yarn"
           cache-dependency-path: packages/plugins/yarn.lock
 
-      # Uncommment the lines below to install & generate zk assets
-      # - working-directory: ./packages/zkp/lib/circom
-      #   run: cargo build --release
-
-      # - working-directory: ./packages/zkp/lib/circom
-      #   run: cargo install --path circom
-
-      # - working-directory: ./packages/zkp
-      #   run: yarn install --frozen-lockfile
-
-      # - working-directory: ./packages/zkp
-      #   run: yarn build
-
       - name: Install Yarn dependencies
         run: yarn install --frozen-lockfile
 
       - name: Copy env file
         run: cp .env.example .env
 
-      - name: Run hardhat compile
-        run: yarn hardhat compile
+      - name: Run hardhat build
+        run: yarn build
+
+      - name: Start geth node & bundler in background
+        run: ./script/start.sh &
+
+      - name: Wait for bundler at port 3000
+        run: RPC_URL='localhost:3000' SLEEP_DURATION_SECONDS=1 ./script/wait-for-rpc.sh
+
+      - name: Run hardhat integration tests
+        run: yarn hardhat test

.gitmodules

@@ -16,14 +16,11 @@
 [submodule "packages/plugins/lib/account-abstraction"]
 	path = packages/plugins/lib/account-abstraction
 	url = https://github.com/eth-infinitism/account-abstraction
-[submodule "packages/zkp/lib/circom"]
-	path = packages/zkp/lib/circom
-	url = https://github.com/iden3/circom.git
-[submodule "packages/barebones/lib/openzeppelin-contracts"]
-	path = packages/barebones/lib/openzeppelin-contracts
+[submodule "archive/barebones/lib/openzeppelin-contracts"]
+	path = archive/barebones/lib/openzeppelin-contracts
 	url = https://github.com/openzeppelin/openzeppelin-contracts
-[submodule "packages/barebones/lib/forge-std"]
-	path = packages/barebones/lib/forge-std
+[submodule "archive/barebones/lib/forge-std"]
+	path = archive/barebones/lib/forge-std
 	url = https://github.com/foundry-rs/forge-std
 [submodule "packages/plugins/lib/kernel"]
 	path = packages/plugins/lib/kernel

README.md

@@ -1,36 +1,40 @@
 # Wallet Account eXperiments (WAX)
-WAX's goal is to deliver set of production-ready components that help developers easily utilise cryptographic primitives in smart accounts
 
-We seek to achieve this with a three pronged approach:
-1. Showcase, via examples, the benefits of cryptographic primitives in smart accounts
-   - including examples of novel use cases that compose smart account modules
-2. Develop an easy-to-use opinionated SDK that makes integrating these benefits easy for non-web3 devs
-3. Provide a focused dev environment for the integration of more primitives into smart accounts
+![WAX Logo](./waxGreenLogo.png)
 
-## Components **(diagram outdated)**
-The showcase dApps are comprised of application specific code (pink) that leverages the SDK (yellow).
-The SDK contains the off-chain companion of corresponding on-chain cryptographic primitives (grey).
-Existing smart accounts will be used to demonstrate integration of the primitives in 4337-compatible verification logic.
+Primary monorepo for the Wallet Account eXperiments (WAX) project, which focuses on integrating novel & useful cryptographic technologies into the Ethereum Account Abstraction (AA) ecosytem to improve the experience of using accounts. We build on top of [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) & related specs.
 
-**Diagram**: current explorations and proposed development
+# Using this monorepo
+Are you looking to build a plugin/module for the AA/ERC-4337 ecosystem and want examples & tooling? Check out [the plugins package](./packages/plugins/).
 
-![WAX Composition](./docs/images/wax-composition.svg)
+Are you interested in compressing ERC-4337 data? Start with [the compression package](./packages/compression/)
 
-- The green areas are WAX's focus.
-- Within the SDK there will be additions that enable projects to readily adopt novel features. 
-- On-chain, between smart contracts and primitives, the verification data+logic will be designed to be composable. Smart accounts can then dynamically benefit from more than one primitive, and this will be developed in sync with broader smart account modularisation.
+## Compression
+[packages/compression](./packages//compression/)
 
-# Using this monorepo
-## packages/demos
-You're a web dev and want to bring the latest web3 capabilities to your product/users.
-Here you will not only find 'hello world' wrappers of base primitives, but also composite examples highlighting novel product features.
-
-## packages/sdk
-The sdk is useful for:
-- non-web3 builders wanting to leverage the latest smart account capabiltiies
-- SDK devs who also want to support interaction with the bleeding edge of smart account verification capabilities
-
-## packages/plugins
-You're a smart account dev and would like to integrate new primitives
-New verification schemes are integrated into existing open smart accounts here.
-This is where modularised byte verification is developed.
+Contracts implementing compression for ERC-4337 accounts to reduce data being posted from rollups.
+
+## Demos
+[packages/demos](./packages/demos/)
+
+Demos showcasing WAX components.
+
+## Deterministic Deployer
+[packages/deterministic-deployer](./packages/deterministic-deployer/)
+
+Deploys contracts to deterministic addresses.
+
+## Plugins
+[packages/plugins](./packages/plugins/)
+
+Plugins/modules for smart contracts accounts, including test scaffolding.
+
+## SDK
+[packages/sdk](./packages/sdk/)
+
+SDK code to help with ERC-4337 interactions.
+
+## Archive
+[archive](./archive/)
+
+Work & projects that are no longer actively used but could be useful as references.

archive/README.md

@@ -0,0 +1,14 @@
+# Archive
+This directory contains work & projects that are no longer active or maintained but could be useful as references
+
+## Barebones
+
+Lightweight Smart Account framework
+
+## Images
+
+Older technical diagrams for WAX project
+
+## ZKP
+
+Circuits related to ERC-4337 accounts & a TypeScript ZKEmail relayer

packages/zkp/README.md → archive/zkp/README.md

@@ -2,6 +2,8 @@
 
 Based on https://github.com/privacy-scaling-explorations/zkp-app-boilerplate/tree/main/circuits
 
+Includes a protoype [TypeScript ZKEmail relayer](./relayer/).
+
 WARNING: These circuits are unsafe and are currently not recommended for production use.
 
 ## Required
@@ -11,17 +13,11 @@ WARNING: These circuits are unsafe and are currently not recommended for product
 
 ## Setup
 
-**Step 1**: Download git submodules.
-
-```sh
-git submodule update --init
-```
-
-**Step 2**: Install circom.
+Install circom following [these instructions](https://docs.circom.io/getting-started/installation/)
 
-Follow [these instructions](https://docs.circom.io/getting-started/installation/) replacing the git clone with `cd lib/circom`.
+The last working version was `v2.1.8`, [commit](https://github.com/iden3/circom/commit/f0deda416abe91e5dd906c55507c737cd9986ab5)
 
-**Step 3**: Install NodeJS dependencies.
+**Step 2**: Install NodeJS dependencies.
 
 ```sh
 yarn
@@ -42,4 +38,4 @@ yarn test
 
 ## Other Commands
 
-See [package.json](./package.json)
+See [package.json](./package.json)

packages/README.md

@@ -1,25 +1,3 @@
 # Packages
 
-## Barebones
-
-Lightweight Smart Account
-
-## Compression
-
-Contracts implementing compression for ERC-4337 accounts
-
-## Demos
-
-Demos showcasing WAX components
-
-## Plugins
-
-Plugins for Smart Accounts
-
-## SDK
-
-(Prototype) SDK code to help with ERC-4337 interactions
-
-## ZKP
-
-Circuits related to ERC-4337 accounts and a typescript relayer
+See [top level README](../README.md)

packages/compression/README.md

@@ -1,6 +1,8 @@
-# Compression for 4337
+# Compression for ERC-4337
 
-Contracts implementing compression for 4337 wallets.
+Contracts implementing compression for ERC-4337 accountss. This work is compatible with ERC-4337 v0.6.
+
+See https://hackmd.io/@voltrevo/Bkz8syuUp for more details & performance.
 
 ## Performance
 

packages/demos/README.md

@@ -1 +1,14 @@
-# Demos
+# Demos
+Demos of WAX modules & functionality
+
+[Email Recovery](./email-recovery/)
+
+Demo of account recovery via email using https://github.com/zkemail/email-recovery
+
+[Fee Calculator](./fee-calculator/)
+
+Calculator to assist in determing if it is cheaper to use BLS + compression on rollups vs. a normal transaction/UserOp
+
+[In Page](./email-recovery/)
+
+Showcase of experimental modules bult by WAX team.

packages/deterministic-deployer/README.md

@@ -0,0 +1,5 @@
+# Determinisitic Deployer
+
+Deploys contracts to deterministic addresses
+
+Based on create2 and the deployer contract from https://github.com/Arachnid/deterministic-deployment-proxy

packages/plugins/README.md

@@ -1,30 +1,49 @@
 # Plugins
 
-Please note, these plugins are in a pre-alpha state and are not ready for production use. In their current state, the plugins are meant for testing and experimentation.
+Experimental plugins, modules, components for use with [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) (`v0.7.0`) compatible smart contract accounts. Most are currently built on top of Safe.
+These plugins are in a pre-alpha state and are not ready for production use. They are intended for experimentation.
 
-# Getting Started
+This package is a hybrid Foundry & Hardhat project. Foundry is used for unit & integration testing, with Hardhat for end-to-end testing & examples of using a plugin in JavaScript/TypeScript runtime.
+
+## When you should use this package
+
+- If you are building a ERC-4337 plugin, module, or component and want end-to-end tooling & testing harnesses to make sure your it is compatible within the ERC-4337/Ethereum AA ecosystem. These can include but are not limited to:
+  - Validation
+  - Account Recovery
+  - Paymasters
+- If you are building a module for an ERC-4437 Safe.
+- If you are interested in experimenting with calldata compression. See also [the compression package](../compression/).
+- If you have an interesting idea to integrate a novel cryptographic primitive or zero knowledge proof into the Ethereum AA ecosystem and want a place to start.
+
+## When you shouldn't use this package
+
+If you are developing a plugin/module for use with an ERC-4337 module spec, such as:
+- ERC-7579, use https://docs.rhinestone.wtf/modulekit as a base instead.
+- ERC-6900, use https://www.erc6900.io/build-a-plugin as a base instead.
+
+## Getting Started
 
 1. `cd packages/plugins`
 2. Run `yarn submodules` to initialize git submodules
 3. Run `yarn` to install hardhat dependencies
 4. Run `forge install` to install foundry dependencies
 5. Run `cp .env.example .env` to create an `.env` file with the values from `.env.example`
 
-## Build & generate Typechain definitions
+### Build & generate Typechain definitions
 
 ```bash
 yarn build
 ```
 
-## Forge tests
+### Forge tests
 
 ```bash
 forge test --no-match-path test/unit/safe/SafeZkEmailRecoveryPlugin.t.sol -vvv
 ```
 
-## Hardhat tests
+### Hardhat tests
 
-To run the hardhat tests, you'll need to run a node and a bundler as some of them are integration tests:
+To run the hardhat tests, you'll need to run a geth node & bundler as some of them are integration tests:
 
 1. Start a geth node, fund accounts, deploy Safe contracts, and start a bundler:
 
@@ -39,3 +58,8 @@ To run the hardhat tests, you'll need to run a node and a bundler as some of the
 ```bash
 yarn hardhat test
 ```
+
+### Things to keep in mind
+
+- When writing Hardhat tests in the [e2e directory](./test/e2e/), DO NOT USE the `hre` ([Hardhat Runtime Environment](https://hardhat.org/hardhat-runner/docs/advanced/hardhat-runtime-environment)) when deploying contracts & interacting on chain. We do not use the normal internal Hardhat runtime as we need to run against a local geth instance & bundler to fully simulate the ERC-4337 flow end-to-end.
+- Be mindful of the [opcode & storage limitations imposed by ERC-4337](https://eips.ethereum.org/EIPS/eip-7562).

packages/plugins/package.json

@@ -11,9 +11,6 @@
     "build": "hardhat compile",
     "lint": "eslint . --ext js,jsx,ts,tsx --report-unused-disable-directives --max-warnings 0"
   },
-  "dependencies": {
-    "@getwax/circuits": "../zkp"
-  },
   "devDependencies": {
     "@account-abstraction/contracts": "0.7.0",
     "@account-abstraction/utils": "^0.6.0",