docs: update the docs

README.md

@@ -1,22 +1,46 @@
-# World ID State Bridge for Linea
+# worldcoin-bridge-linea
+
+![spec](docs/state-bridge.svg)
 
 ## Description
 
-This repository will contain the code for the Worldcoin state bridge, specifically designed for the Linea blockchain.
-The bridge facilitates state synchronization between the WorldID Ethereum mainnet deployment and the Linea network.
+State bridge between the WorldID Ethereum mainnet deployment and Linea. The [spec](./docs/spec.md) can be found in
+`docs/spec.md`.
 
 ## Deployments
 
-The addresses of the contract deployments for production and staging will be available in docs/deployments.md.
+The addresses of the contract deployments for production and staging can be found in
+[`docs/deployments.md`](./docs/deployments.md#production).
 
 ## Supported Networks
 
-- Linea (zkEVM Layer 2 on Ethereum)
+This repository implements a World ID state bridge specifically for Linea. For context, the original World ID state
+bridge supports Polygon PoS and OP stack chains (Optimism and Base), which can be found
+[here](https://github.com/worldcoin/world-id-state-bridge). Additionally, there's a standalone bridge similar to this
+one for Scroll, available [here](https://github.com/dragan2234/worldcoin-scroll-bridge).
+
+## Prerequisites
+
+This repository uses Bun as a dependency manager, script execution environment and so on. To install Bun, refer to its
+[webpage](https://bun.sh/docs/installation). Other commands listed below assume you have Bun installed.
+
+## Documentation
+
+Run `bun doc` to build and deploy a simple documentation webpage on [localhost:3000](https://localhost:3000). Uses
+[`forge doc`](https://book.getfoundry.sh/reference/forge/forge-doc#forge-doc) under the hood and sources information
+from the `world-id-state-bridge` contracts [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html)
+documentation.
 
 ## Usage
 
 This is a list of the most frequently needed commands.
 
+### Install Dependencies
+
+```sh
+bun install
+```
+
 ### Build
 
 Build the contracts:
@@ -33,50 +57,34 @@ Delete the build artifacts and cache directories:
 $ forge clean
 ```
 
-### Compile
-
-Compile the contracts:
-
-```sh
-$ forge build
-```
-
 ### Coverage
 
-Get a test coverage report:
+Generate test coverage and output result to the terminal:
 
 ```sh
-$ forge coverage
+$ bun run test:coverage
 ```
 
-### Deploy
+### Format
 
-Deploy to Anvil:
+Format the contracts with `forge fmt` and the rest of the files (.js, .md) with Prettier:
 
 ```sh
-$ forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545
+bun run format
 ```
 
-For this script to work, you need to have a `MNEMONIC` environment variable set to a valid
-[BIP39 mnemonic](https://iancoleman.io/bip39/).
-
-For instructions on how to deploy to a testnet or mainnet, check out the
-[Solidity Scripting](https://book.getfoundry.sh/tutorials/solidity-scripting.html) tutorial.
-
-### Format
+### Gas Usage
 
-Format the contracts:
+Get a gas report:
 
 ```sh
-$ forge fmt
+bun run snapshot
 ```
 
-### Gas Usage
-
-Get a gas report:
+Run gas benchmarks on the tests:
 
 ```sh
-$ forge test --gas-report
+bun run bench
 ```
 
 ### Lint
@@ -95,18 +103,19 @@ Run the tests:
 $ forge test
 ```
 
-Generate test coverage and output result to the terminal:
+### Deploy
+
+Deploy to Anvil:
 
 ```sh
-$ bun run test:coverage
+$ forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545
 ```
 
-Generate test coverage with lcov report (you'll have to open the `./coverage/index.html` file in your browser, to do so
-simply copy paste the path):
+For this script to work, you need to have a `MNEMONIC` environment variable set to a valid
+[BIP39 mnemonic](https://iancoleman.io/bip39/).
 
-```sh
-$ bun run test:coverage:report
-```
+For instructions on how to deploy to a testnet or mainnet, check out the
+[Solidity Scripting](https://book.getfoundry.sh/tutorials/solidity-scripting.html) tutorial.
 
 ## Contributing
 

foundry.toml

@@ -20,6 +20,25 @@ fs_permissions = [{ access = "read-write", path = "src/script/.deploy-config.jso
 fuzz = { runs = 10_000 }
 verbosity = 4
 
+# === Test All Profile ========================================================
+
+[profile.bench]
+# We make the optimiser run a lot more for production, hoping to reduce our gas
+# costs.
+optimizer_runs = 20000
+
+# Make things chattier when debugging in case of test failures, giving us more
+# information with which to debug the issue. At this level, stack traces for
+# failing tests are displayed.
+verbosity = 3
+
+# We can specify the contracts to track gas data for by tracing.
+gas_reports = [
+  "WorldIDIdentityManager",
+  "MockWorldIDIdentityManager",
+  "Verifier",
+]
+
 # [etherscan]
 # mainnet = { key = "${API_KEY_ETHERSCAN}" }
 # sepolia = { key = "${API_KEY_ETHERSCAN}" }

package.json

@@ -48,9 +48,12 @@
     "lint:sol": "forge fmt --check && bun solhint {script,src,test}/**/*.sol",
     "prettier:check": "prettier --check \"**/*.{json,md,yml}\" --ignore-path \".prettierignore\"",
     "prettier:write": "prettier --write \"**/*.{json,md,yml}\" --ignore-path \".prettierignore\"",
+    "format": "forge fmt; npx prettier --write \"**/*.{js,json,md,yml}\" --ignore-path \".prettierignore\"",
     "test": "forge test",
     "test:coverage": "forge coverage",
-    "test:coverage:report": "forge coverage --report lcov && genhtml lcov.info --branch-coverage --output-dir coverage",
-    "propagate": "node src/script/propagateRoot.js"
+    "snapshot": "FOUNDRY_PROFILE=bench forge snapshot",
+    "bench": "FOUNDRY_PROFILE=bench forge test --gas-report",
+    "propagate": "node src/script/propagateRoot.js",
+    "doc": "forge doc --build; forge doc --serve -p 3000"
   }
 }