Complete migration to MkDocs: replace GitBook with MkDocs (mkdocs-material)

Author: tomteman

.github/workflows/deploy.yml

@@ -0,0 +1,56 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/mkdocs-ci.yml

@@ -0,0 +1,16 @@
+name: Build Docs
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install -r requirements.txt
+      - run: mkdocs build --strict

SUMMARY.md

@@ -0,0 +1,51 @@
+# Table of contents
+
+- [⭐️ Introduction](index.md)
+- [🧠 Smart Accounts](smart-accounts/)
+  - [README](smart-accounts/README.md)
+  - [Entrypoint Explainer](smart-accounts/entrypoint-explainer.md)
+  - [Session Keys And Delegation](smart-accounts/session-keys-and-delegation.md)
+  - [The Application Layer Wallets And Sdks](smart-accounts/the-application-layer-wallets-and-sdks.md)
+  - [Modular Standards](smart-accounts/modular-accounts.md)
+
+- [📦 Bundlers](bundlers/)
+  - [README](bundlers/README.md)
+  - [Compatibility Test Suite](bundlers/compatibility-test-suite.md)
+  - [Userop Mempool Overview](bundlers/userop-mempool-overview.md)
+  - [Censorship Resistance](bundlers/censorship-resistance.md)
+  - [Simulation Requirements](bundlers/simulation-requirements.md)
+  - [Monitoring And Metrics](bundlers/monitoring-and-metrics.md)
+
+- [💰 Paymasters](paymasters/)
+  - [README](paymasters/README.md)
+  - [Paymaster Types](paymasters/types.md)
+  - [Security And Griefing](paymasters/security-and-griefing.md)
+  - [Design Patterns](paymasters/design-patterns.md)
+  - [Examples And SDKs](paymasters/examples-and-sdks.md)
+
+- [⛓️ L2s](l2s/)
+  - [README](l2s/README.md)
+  - [RIP-7560](l2s/rip-7560.md)
+  - [OP Superchain ERC-4337 Dataset Explained](l2s/superchain-4337-dataset-explained.md)
+  - [How To Create Your Own ERC-4337 Metrics](l2s/how-to-create-your-own-4337-metrics.md)
+
+- [🌿 Core Standards](core-standards/)
+  - [README](core-standards/README.md)
+  - [ERC-4337](core-standards/erc-4337.md)
+  - [ERC-7562](core-standards/erc-7562.md)
+  - [EIP-7701](core-standards/eip-7701.md)
+  - [RIP-7560](core-standards/rip-7560.md)
+  - [RIP-7711](core-standards/rip-7711.md)
+  - [RIP-7712](core-standards/rip-7712.md)
+
+- [🤝 Community](community/)
+  - [README](community/README.md)
+  - [Ethereum Foundation Grants](community/ef-grants.md)
+  - [AA Hub @ Devcon 7](community/aa-hub-devcon7.md)
+  - [Bug Bounty](community/bug-bounty.md)
+
+- [📚 Resources](resources/)
+  - [README](resources/README.md)
+  - [Reading Materials](resources/reading-material.md)
+  - [Videos](resources/videos.md)
+  - [FAQ](resources/faqs.md)

assets/images/ERC-4337-team-logo-color.png

@@ -1,11 +1,8 @@
----
-title: Bundlers
-description: Overview of Bundlers in the ERC-4337 architecture.
-sidebar_position: 1
----
 
 # 📦 Bundlers
 
+## Overview of Bundlers in the ERC-4337 architecture.
+
 Bundlers are the relayers of ERC-4337. They collect `UserOperations`, simulate them for validity, and package them into a call to the EntryPoint contract on-chain.
 
 They are a critical part of the infrastructure that makes Account Abstraction work without consensus-layer changes.
@@ -25,6 +22,7 @@ They are a critical part of the infrastructure that makes Account Abstraction wo
 ## 🔍 Why Are They Needed?
 
 Ethereum’s base protocol doesn’t natively support `UserOperation`-style logic. Bundlers:
+
 - Act like “miners for smart wallets”
 - Provide validation guarantees for off-chain mempools
 - Allow modular signature and sponsorship logic without protocol changes
@@ -36,6 +34,7 @@ Ethereum’s base protocol doesn’t natively support `UserOperation`-style logi
 All bundlers interact with a canonical **EntryPoint contract**, which is deployed at a fixed address per network (e.g. v0.6, v0.7, v0.8).
 
 They must support:
+
 - `handleOps()` to process batched `UserOperations`
 - `simulateValidation()` to precheck operations without state changes
 
@@ -44,6 +43,7 @@ They must support:
 ## 🤑 Incentives
 
 Bundlers receive:
+
 - Priority fees specified in each `UserOperation`
 - Refunds from the account or Paymaster for gas used
 

assets/images/social-background.jpeg

@@ -1,9 +1,7 @@
----
-title: Censorship Resistance
-description: How the alt mempool and Shared Mempool protect UserOp inclusion.
-sidebar_position: 4
----
-# Censorship Resistance in ERC-4337
+# Censorship Resistance
+
+## How the alt mempool and Shared Mempool protect UserOp inclusion.
+
 
 From the very beginning, ERC-4337 was designed to support a decentralized, censorship-resistant transaction flow for Account Abstraction. A key part of that vision was the creation of a **separate, peer-to-peer mempool for UserOperations**, distinct from Ethereum’s native transaction mempool. However, realizing this architecture took time — and until late 2024, most bundlers relied on **private, isolated queues** that undermined the original goals.
 
@@ -12,6 +10,7 @@ From the very beginning, ERC-4337 was designed to support a decentralized, censo
 ## ⚠️ Centralization Risk Without Global Propagation
 
 In a fragmented ecosystem:
+
 - Bundlers can selectively drop or ignore `UserOperation`s
 - Users relying on a single RPC or bundler can be censored
 
@@ -56,6 +55,7 @@ The ecosystem is currently transitioning from Stage 1 to Stage 2, with growing a
 ## 🤝 Relevance to EIP-7702
 
 Even outside of ERC-4337, the Shared Mempool helps:
+
 - EIP-7702 introduces temporarily smart-enabled EOAs
 - These can be relayed via the UserOp mempool, not the canonical one
 - This enhances censorship resistance for wallets adopting 7702 logic
@@ -66,7 +66,9 @@ Ethereum.org recommends using the UserOp mempool as a best practice for 7702 onb
 ---
 
 📖 Learn more:
+
 - [Unified ERC-4337 mempool](https://notes.ethereum.org/@yoav/unified-erc-4337-mempool)
+- [Trust me - don't trust anyone](https://erc4337.substack.com/?r=22nd9&utm_campaign=pub&utm_medium=web)
 - [ERC-4337 Shared Mempool Launch](https://etherspot.io/blog/erc-4337-shared-mempool-official-launch-on-ethereum-mainnet-arbitrum-and-optimism/)
 - [Decentralized Future of Shared Mempool](https://medium.com/etherspot/decentralized-future-erc-4337-shared-mempool-launches-on-ethereum-b6c860072f41)
 - [Mempool Stages Framework](https://substack.com/home/post/p-163060056)

docs/SUMMARY.md

@@ -1,14 +1,12 @@
----
-title: Bundler Compatibility Test Suite
-description: Overview and link to external bundler conformance test results.
-sidebar_position: 2
----
 
-# Bundler Compatibility Test Suite
+# Compatibility Test Suite
+
+## Overview and link to external bundler conformance test results.
 
 This Bundler Compatibility Test Suite results page serves as a reference for ongoing compatibility testing across bundlers in the ERC-4337 ecosystem.
 
 An external test suite has been developed to verify that bundlers:
+
 - Correctly implement the EntryPoint interface
 - Respect simulation and validation rules
 - Safely handle edge cases and reverts
@@ -30,9 +28,10 @@ The tests simulate a wide variety of `UserOperations`, from valid edge cases to
 
 Test results are tracked live at:
 
-👉 [https://bundlers.erc4337.io/](https://bundlers.erc4337.io/)
+👉 <a href="https://bundlers.erc4337.io/" target="_blank">https://bundlers.erc4337.io/</a>
 
 This includes:
+
 - A matrix of passing/failing tests for each bundler
 - Notes on client-specific quirks or deviations
 - Historical conformance data

bundlers/README.md docs/bundlers/README.mdbundlers/README.md renamed to docs/bundlers/README.md

@@ -1,10 +1,9 @@
----
-title: Monitoring and Metrics
-description: How to track and debug bundler performance in ERC-4337 systems.
-sidebar_position: 6
----
 
-# Monitoring and Metrics for Bundlers
+# Monitoring and Metrics
+
+## How to track and debug bundler performance in ERC-4337 systems.
+
+
 
 Running a reliable bundler requires robust observability. From mempool activity to simulation results and gas refunds, operators need insight into every layer of the ERC-4337 stack.
 
@@ -13,34 +12,26 @@ Running a reliable bundler requires robust observability. From mempool activity
 ## 📊 What to Monitor
 
 ### UserOp Lifecycle
+
 - Ingress: Count of UserOps received per second
 - Validation results: pass/fail reasons
 - Bundle size and frequency
 - Inclusion latency (time-to-handleOps)
 
 ### Simulation
+
 - Calls to `simulateValidation`
 - Revert rates by failure class (signature, paymaster, initCode)
 - Gas estimation accuracy
 
 ### EntryPoint Interaction
+
 - Successful vs failed `handleOps()` calls
 - Average gas used per UserOp
 - Revenue tracking: priority fee, refund breakdown
 
 ---
 
-## 🧰 Tools and Dashboards
-
-### Custom Logs and Metrics
-- Export Prometheus or OpenTelemetry metrics
-- Log UserOp hashes, error types, and bundling cycles
-
-### Ready-made Dashboards
-- **Pimlico**: Offers a bundler dashboard with real-time metrics and mempool stats
-- **Silius**: Exposes simulation logs and operation state via API
-
----
 
 ## 🔄 Integration with Alerting