From 652e408cfc028e4a5aa64572ba4daf156022b5df Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Thu, 16 Jul 2026 12:33:52 +0200
Subject: [PATCH 1/2] fix(docs): restore version and discovery correctness

---
 .github/workflows/book.yml                    |   11 +-
 CONTRIBUTING.md                               |   20 +-
 README.md                                     |    8 +-
 scripts/check-versions.ts                     |   30 +
 scripts/update.sh                             |   42 +-
 vocs/docs/pages/examples/advanced/README.mdx  |    2 +-
 .../pages/examples/big-numbers/README.mdx     |    2 +-
 .../docs/pages/examples/comparison/README.mdx |    2 +-
 vocs/docs/pages/examples/contracts/README.mdx |    2 +-
 vocs/docs/pages/examples/ens/README.mdx       |    2 +-
 vocs/docs/pages/examples/fillers/README.mdx   |    2 +-
 vocs/docs/pages/examples/layers/README.mdx    |    2 +-
 .../pages/examples/node-bindings/README.mdx   |    2 +-
 .../docs/pages/examples/primitives/README.mdx |    2 +-
 vocs/docs/pages/examples/providers/README.mdx |    2 +-
 vocs/docs/pages/examples/queries/README.mdx   |    2 +-
 vocs/docs/pages/examples/sol-macro/README.mdx |    2 +-
 .../pages/examples/subscriptions/README.mdx   |    2 +-
 .../pages/examples/transactions/README.mdx    |    2 +-
 vocs/docs/pages/examples/wallets/README.mdx   |    2 +-
 .../pages/introduction/getting-started.md     |    6 +-
 vocs/docs/pages/introduction/installation.md  |    3 +-
 vocs/docs/pages/introduction/prompting.md     | 1697 +----------------
 vocs/docs/snippets/installation/alloy.toml    |    1 +
 .../installation/individual-crates.toml       |    4 +
 .../{pages => }/templates/advanced/README.mdx |    0
 .../templates/big-numbers/README.mdx          |    0
 .../templates/comparison/README.mdx           |    0
 .../templates/contracts/README.mdx            |    0
 .../docs/{pages => }/templates/ens/README.mdx |    0
 .../{pages => }/templates/fillers/README.mdx  |    0
 .../{pages => }/templates/layers/README.mdx   |    0
 .../templates/node-bindings/README.mdx        |    0
 .../templates/primitives/README.mdx           |    0
 .../templates/providers/README.mdx            |    0
 .../{pages => }/templates/queries/README.mdx  |    0
 .../templates/sol-macro/README.mdx            |    0
 .../templates/subscriptions/README.mdx        |    0
 .../templates/transactions/README.mdx         |    0
 .../{pages => }/templates/wallets/README.mdx  |    0
 vocs/public/robots.txt                        |    4 +
 vocs/versions.ts                              |    5 +
 vocs/vocs.config.ts                           |   11 +-
 43 files changed, 165 insertions(+), 1707 deletions(-)
 create mode 100644 scripts/check-versions.ts
 create mode 100644 vocs/docs/snippets/installation/alloy.toml
 create mode 100644 vocs/docs/snippets/installation/individual-crates.toml
 rename vocs/docs/{pages => }/templates/advanced/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/big-numbers/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/comparison/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/contracts/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/ens/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/fillers/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/layers/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/node-bindings/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/primitives/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/providers/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/queries/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/sol-macro/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/subscriptions/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/transactions/README.mdx (100%)
 rename vocs/docs/{pages => }/templates/wallets/README.mdx (100%)
 create mode 100644 vocs/public/robots.txt
 create mode 100644 vocs/versions.ts

diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml
index 63849f9b..f1e7f838 100644
--- a/.github/workflows/book.yml
+++ b/.github/workflows/book.yml
@@ -19,8 +19,17 @@ jobs:
           submodules: recursive
       - uses: oven-sh/setup-bun@v2
 
+      - name: Check documented dependency versions
+        run: bun scripts/check-versions.ts
+
       - name: Build Vocs
-        run: cd vocs && bun install && bun run build
+        run: cd vocs && bun install --frozen-lockfile && bun run build
+
+      - name: Check generated discovery files
+        run: |
+          test -f vocs/dist/public/sitemap.xml
+          test -f vocs/dist/public/robots.txt
+          test ! -d vocs/dist/public/templates
 
       # Only prepare for deploy if a push to main
       - name: Setup Pages
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 620c9dcd..36ff9951 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,17 +12,15 @@ expert, we can use your help.
 This guide will help you get started. **Do not let this guide intimidate you**.
 It should be considered a map to help you navigate the process.
 
-The [dev channel][dev] is available for any concerns not covered in this guide,
-please join us!
-
-[dev]: https://t.me/ethers_rs
+For questions not covered here, open a discussion in the
+[Alloy repository](https://github.com/alloy-rs/alloy/discussions).
 
 ## Conduct
 
 The Alloy project adheres to the [Rust Code of Conduct][coc]. This describes
 the _minimum_ behavior expected from all contributors. Instances of violations
 of the Code of Conduct can be reported by contacting the project team at
-[james@prestwich](mailto:james@prestwi.ch).
+[james@prestwi.ch](mailto:james@prestwi.ch).
 
 [coc]: https://www.rust-lang.org/policies/code-of-conduct
 
@@ -98,7 +96,7 @@ specification.
 
 This section lists some commonly needed commands.
 
-First create a [fork](https://github.com/alloy-rs/book/fork).
+First create a [fork](https://github.com/alloy-rs/docs/fork).
 
 Next clone your fork with the `--recurse-submodules` flag:
 
@@ -106,7 +104,12 @@ Next clone your fork with the `--recurse-submodules` flag:
 git clone --recurse-submodules $FORK_URL
 ```
 
-The documentation is built with [`vocs`](https://vocs.dev), you can install `vocs` by using any javascript package manager such as `bun` or `npm`. We prefer `bun`.
+The documentation is built with [`vocs`](https://vocs.dev). Install the pinned
+dependencies with Bun:
+
+```sh
+cd vocs && bun install --frozen-lockfile
+```
 
 To see the book change live run:
 
@@ -116,7 +119,8 @@ cd vocs && bun dev
 
 To perform an update of generated output inspect and run `./scripts/update.sh`.
 
-To add a new section (file) to the book, add it to `./src/SUMMARY.md`.
+To add a new page, create it under `./vocs/docs/pages` and add it to
+`./vocs/sidebar.ts` when it should appear in the primary navigation.
 
 ### Discuss and update
 
diff --git a/README.md b/README.md
index 038ab63d..833016c7 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,6 @@
 
 Documentation for all things Alloy.
 
-[![Telegram chat][telegram-badge]][telegram-url]
-
-[`alloy-rs`]: https://github.com/gakonst/ethers-rs
-[telegram-badge]: https://img.shields.io/endpoint?color=neon&style=for-the-badge&url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Fethers_rs
-[telegram-url]: https://t.me/ethers_rs
-
 View the docs [here](https://alloy.rs/).
 
 ## Contributing
@@ -16,7 +10,7 @@ Thanks for your help improving the project! We are so happy to have you! We have
 [a contributing guide](./CONTRIBUTING.md) to help you get involved in the
 Alloy project.
 
-#### License
+## License
 
 <sup>
 Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
diff --git a/scripts/check-versions.ts b/scripts/check-versions.ts
new file mode 100644
index 00000000..e8764846
--- /dev/null
+++ b/scripts/check-versions.ts
@@ -0,0 +1,30 @@
+import { versions } from '../vocs/versions'
+
+const generatedSnippets = new Map([
+  [
+    new URL('../vocs/docs/snippets/installation/alloy.toml', import.meta.url),
+    `alloy = "${versions.alloy}"\n`,
+  ],
+  [
+    new URL('../vocs/docs/snippets/installation/individual-crates.toml', import.meta.url),
+    [
+      '[dependencies]',
+      `alloy-primitives = { version = "${versions.alloyCore}", default-features = false, features = ["rand", "serde", "map-foldhash"] }`,
+      `alloy-provider = { version = "${versions.alloy}", default-features = false, features = ["ipc"] }`,
+      '# ..snip..',
+      '',
+    ].join('\n'),
+  ],
+])
+
+let valid = true
+
+for (const [url, expected] of generatedSnippets) {
+  const actual = await Bun.file(url).text()
+  if (actual !== expected) {
+    valid = false
+    console.error(`${url.pathname} is stale; expected documentation versions from vocs/versions.ts`)
+  }
+}
+
+if (!valid) process.exit(1)
diff --git a/scripts/update.sh b/scripts/update.sh
index 16f4a861..5193e3fe 100755
--- a/scripts/update.sh
+++ b/scripts/update.sh
@@ -20,7 +20,7 @@ SNIPPETS_PATH="./vocs/docs/snippets"
 # MDX Snippets path
 MDX_SNIPPETS_PATH="./vocs/docs/pages/examples"
 # Templates path
-MDX_TEMPLATES_PATH="./vocs/docs/pages/templates"
+MDX_TEMPLATES_PATH="./vocs/docs/templates"
 # Sidebar items TS file
 SIDEBAR_ITEMS_PATH="./vocs/example-items.ts"
 
@@ -32,7 +32,7 @@ SIDEBAR_ITEMS_PATH="./vocs/example-items.ts"
 # the example code and instructions on how to run the example.
 # 3. Print any differences between the current and updated example files list.
 function main () {
-  log $GREEN "Updating..."
+  log "$GREEN" "Updating..."
 
   # Change directory to project root
   SCRIPT_PATH="$( cd "$( dirname "$0" )" >/dev/null 2>&1 && pwd )"
@@ -45,16 +45,16 @@ function main () {
   git submodule foreach git pull origin main
 
   # Create the $SNIPPETS_PATH directory if it doesn't exist
-  mkdir -p $SNIPPETS_PATH
+  mkdir -p "$SNIPPETS_PATH"
 
   # Create the $MDX_SNIPPETS_PATH directory if it doesn't exist
-  mkdir -p $MDX_SNIPPETS_PATH
+  mkdir -p "$MDX_SNIPPETS_PATH"
 
   # Copy the directory and files from `lib/examples/examples` to $SNIPPETS_PATH
   echo "Copying examples to $SNIPPETS_PATH"
-  cp -r ./lib/examples/examples/* $SNIPPETS_PATH/
+  cp -r ./lib/examples/examples/* "$SNIPPETS_PATH/"
   
-  log $GREEN "Copied examples to $SNIPPETS_PATH"
+  log "$GREEN" "Copied examples to $SNIPPETS_PATH"
 
   # Get the commit hash of the latest commit in the examples repository
   EXAMPLES_COMMIT_HASH=$(git -C ./lib/examples rev-parse HEAD)
@@ -64,30 +64,30 @@ function main () {
 
   # Clean up existing examples
   echo "Cleaning up existing examples"
-  rm -rf $MDX_SNIPPETS_PATH/*
+  rm -rf "${MDX_SNIPPETS_PATH:?}/"*
 
   # Create the $MDX_SNIPPETS_PATH directory if it doesn't exist
-  mkdir -p $MDX_SNIPPETS_PATH
+  mkdir -p "$MDX_SNIPPETS_PATH"
 
   # Create example markdown files
   for CODE_DIRPATH in ./lib/examples/examples/*/; do
     # Get the example category directory name
-    EXAMPLE_DIRNAME=$(basename $CODE_DIRPATH)
+    EXAMPLE_DIRNAME=$(basename "$CODE_DIRPATH")
 
     # Populate the $MDX_SNIPPETS_PATH directory with the example category directory
-    mkdir -p $MDX_SNIPPETS_PATH/$EXAMPLE_DIRNAME
+    mkdir -p "$MDX_SNIPPETS_PATH/$EXAMPLE_DIRNAME"
 
     # Populate the $MDX_TEMPLATES_PATH directory with the example category directory if it doesn't exist
-    mkdir -p $MDX_TEMPLATES_PATH/$EXAMPLE_DIRNAME
-    touch $MDX_TEMPLATES_PATH/$EXAMPLE_DIRNAME/README.mdx
-    cp $MDX_TEMPLATES_PATH/$EXAMPLE_DIRNAME/README.mdx $MDX_SNIPPETS_PATH/$EXAMPLE_DIRNAME/README.mdx
+    mkdir -p "$MDX_TEMPLATES_PATH/$EXAMPLE_DIRNAME"
+    touch "$MDX_TEMPLATES_PATH/$EXAMPLE_DIRNAME/README.mdx"
+    cp "$MDX_TEMPLATES_PATH/$EXAMPLE_DIRNAME/README.mdx" "$MDX_SNIPPETS_PATH/$EXAMPLE_DIRNAME/README.mdx"
 
     # For every example file in the examples directory
     # - Create a markdown file in the $MDX_SNIPPETS_PATH directory
     # - Insert the example code by reference in the markdown file
     # - Include the template content by pointer if it exists
-    for EXAMPLE_FILEPATH in $CODE_DIRPATH/examples/*.rs; do
-      EXAMPLE_FILENAME=$(basename $EXAMPLE_FILEPATH .rs)
+    for EXAMPLE_FILEPATH in "$CODE_DIRPATH"examples/*.rs; do
+      EXAMPLE_FILENAME=$(basename "$EXAMPLE_FILEPATH" .rs)
       MDX_TEMPLATE_FILEPATH="$MDX_TEMPLATES_PATH/$EXAMPLE_DIRNAME/README.mdx"
       EXAMPLE_README_MDX=$MDX_SNIPPETS_PATH/$EXAMPLE_DIRNAME/README.mdx
       MDX_SNIPPET=$MDX_SNIPPETS_PATH/$EXAMPLE_DIRNAME/$EXAMPLE_FILENAME.mdx
@@ -95,9 +95,9 @@ function main () {
       
       # Include the template content pointer if the template exists
       TEMPLATE_CONTENT=$(
-        [ -f $MDX_TEMPLATE_FILEPATH ] && \
+        [ -f "$MDX_TEMPLATE_FILEPATH" ] && \
         printf "%s\n\n%s\n" \
-          "import Template from '../../templates/$EXAMPLE_DIRNAME/README.mdx'" \
+          "import Template from '../../../templates/$EXAMPLE_DIRNAME/README.mdx'" \
           "<Template />" || \
         echo ""
       )
@@ -124,7 +124,7 @@ To run this example:
 - Run: \`cargo run --example $EXAMPLE_FILENAME\`
 
 \`\`\`rust
-// [!include ~/snippets/$EXAMPLE_DIRNAME/examples/$(basename $EXAMPLE_FILEPATH)]
+// [!include ~/snippets/$EXAMPLE_DIRNAME/examples/$(basename "$EXAMPLE_FILEPATH")]
 \`\`\`
 
 Find the source code on Github [here](https://github.com/alloy-rs/examples/tree/$EXAMPLES_COMMIT_HASH/examples/$EXAMPLE_DIRNAME/examples/$EXAMPLE_FILENAME.rs).
@@ -190,11 +190,11 @@ EOF
   UPDATED_EXAMPLE_FILES=$(find $SNIPPETS_PATH -type f)
   diff <(echo "$CURRENT_EXAMPLE_FILES") <(echo "$UPDATED_EXAMPLE_FILES") || true
 
-  log $YELLOW "Update \`./vocs/docs/pages/templates/*/README.md\` if necessary!"
+  log "$YELLOW" "Update \`./vocs/docs/templates/*/README.mdx\` if necessary!"
 
-  log $GREEN "Done"
+  log "$GREEN" "Done"
 }
 
 # Run the main function
 # This prevents partial execution in case of incomplete downloads
-main
\ No newline at end of file
+main
diff --git a/vocs/docs/pages/examples/advanced/README.mdx b/vocs/docs/pages/examples/advanced/README.mdx
index 2f095e18..104b6196 100644
--- a/vocs/docs/pages/examples/advanced/README.mdx
+++ b/vocs/docs/pages/examples/advanced/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/advanced/README.mdx'
+import Template from '../../../templates/advanced/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/big-numbers/README.mdx b/vocs/docs/pages/examples/big-numbers/README.mdx
index c7855106..cdbc0d37 100644
--- a/vocs/docs/pages/examples/big-numbers/README.mdx
+++ b/vocs/docs/pages/examples/big-numbers/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/big-numbers/README.mdx'
+import Template from '../../../templates/big-numbers/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/comparison/README.mdx b/vocs/docs/pages/examples/comparison/README.mdx
index 220b75e0..408bcf68 100644
--- a/vocs/docs/pages/examples/comparison/README.mdx
+++ b/vocs/docs/pages/examples/comparison/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/comparison/README.mdx'
+import Template from '../../../templates/comparison/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/contracts/README.mdx b/vocs/docs/pages/examples/contracts/README.mdx
index ec378a7c..f1c0f648 100644
--- a/vocs/docs/pages/examples/contracts/README.mdx
+++ b/vocs/docs/pages/examples/contracts/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/contracts/README.mdx'
+import Template from '../../../templates/contracts/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/ens/README.mdx b/vocs/docs/pages/examples/ens/README.mdx
index 55f3f6b8..a7aad23e 100644
--- a/vocs/docs/pages/examples/ens/README.mdx
+++ b/vocs/docs/pages/examples/ens/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/ens/README.mdx'
+import Template from '../../../templates/ens/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/fillers/README.mdx b/vocs/docs/pages/examples/fillers/README.mdx
index 0691db75..c8a25749 100644
--- a/vocs/docs/pages/examples/fillers/README.mdx
+++ b/vocs/docs/pages/examples/fillers/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/fillers/README.mdx'
+import Template from '../../../templates/fillers/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/layers/README.mdx b/vocs/docs/pages/examples/layers/README.mdx
index aeeec994..a3d99a04 100644
--- a/vocs/docs/pages/examples/layers/README.mdx
+++ b/vocs/docs/pages/examples/layers/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/layers/README.mdx'
+import Template from '../../../templates/layers/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/node-bindings/README.mdx b/vocs/docs/pages/examples/node-bindings/README.mdx
index 5a5a131c..6e4692a6 100644
--- a/vocs/docs/pages/examples/node-bindings/README.mdx
+++ b/vocs/docs/pages/examples/node-bindings/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/node-bindings/README.mdx'
+import Template from '../../../templates/node-bindings/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/primitives/README.mdx b/vocs/docs/pages/examples/primitives/README.mdx
index f17fa45f..1ceaf4ce 100644
--- a/vocs/docs/pages/examples/primitives/README.mdx
+++ b/vocs/docs/pages/examples/primitives/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/primitives/README.mdx'
+import Template from '../../../templates/primitives/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/providers/README.mdx b/vocs/docs/pages/examples/providers/README.mdx
index 321313a7..ec743b5f 100644
--- a/vocs/docs/pages/examples/providers/README.mdx
+++ b/vocs/docs/pages/examples/providers/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/providers/README.mdx'
+import Template from '../../../templates/providers/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/queries/README.mdx b/vocs/docs/pages/examples/queries/README.mdx
index 7c69451b..fe3f5226 100644
--- a/vocs/docs/pages/examples/queries/README.mdx
+++ b/vocs/docs/pages/examples/queries/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/queries/README.mdx'
+import Template from '../../../templates/queries/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/sol-macro/README.mdx b/vocs/docs/pages/examples/sol-macro/README.mdx
index 636ae78e..3b5199bc 100644
--- a/vocs/docs/pages/examples/sol-macro/README.mdx
+++ b/vocs/docs/pages/examples/sol-macro/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/sol-macro/README.mdx'
+import Template from '../../../templates/sol-macro/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/subscriptions/README.mdx b/vocs/docs/pages/examples/subscriptions/README.mdx
index 9093be87..5984d305 100644
--- a/vocs/docs/pages/examples/subscriptions/README.mdx
+++ b/vocs/docs/pages/examples/subscriptions/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/subscriptions/README.mdx'
+import Template from '../../../templates/subscriptions/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/transactions/README.mdx b/vocs/docs/pages/examples/transactions/README.mdx
index 52ee6185..22a3b574 100644
--- a/vocs/docs/pages/examples/transactions/README.mdx
+++ b/vocs/docs/pages/examples/transactions/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/transactions/README.mdx'
+import Template from '../../../templates/transactions/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/examples/wallets/README.mdx b/vocs/docs/pages/examples/wallets/README.mdx
index fa89349b..f775ca6f 100644
--- a/vocs/docs/pages/examples/wallets/README.mdx
+++ b/vocs/docs/pages/examples/wallets/README.mdx
@@ -1,3 +1,3 @@
-import Template from '../../templates/wallets/README.mdx'
+import Template from '../../../templates/wallets/README.mdx'
 
 <Template />
diff --git a/vocs/docs/pages/introduction/getting-started.md b/vocs/docs/pages/introduction/getting-started.md
index 6d03c4c4..1d8182c0 100644
--- a/vocs/docs/pages/introduction/getting-started.md
+++ b/vocs/docs/pages/introduction/getting-started.md
@@ -1,4 +1,5 @@
 ---
+title: Getting Started
 description: Get started with Alloy, the high-performance Rust toolkit for Ethereum and EVM-based blockchains
 ---
 
@@ -274,10 +275,7 @@ Alloy is a collection of modular crates that can be used independently.
 Meta-crates can lead to dependencies bloat increasing compile-time. For large projects where compile time can be an issue, we recommend using crates independently as in when required.
 
 ```toml [Cargo.toml]
-[dependencies]
-alloy-primitives = { version = "1.0", default-features = false, features = ["rand", "serde", "map-foldhash"] }
-alloy-provider = { version = "0.15", default-features = false, features = ["ipc"] }
-# ..snip..
+// [!include ~/snippets/installation/individual-crates.toml]
 ```
 
 This allows you to have granular control over the dependencies and features you use in your project.
diff --git a/vocs/docs/pages/introduction/installation.md b/vocs/docs/pages/introduction/installation.md
index 421af91d..ea612425 100644
--- a/vocs/docs/pages/introduction/installation.md
+++ b/vocs/docs/pages/introduction/installation.md
@@ -1,4 +1,5 @@
 ---
+title: Installation
 description: Install Alloy with cargo and configure the necessary feature flags for your blockchain development needs
 ---
 
@@ -15,7 +16,7 @@ cargo add alloy
 Alternatively, you can add the following to your `Cargo.toml` file:
 
 ```toml
-alloy = "1.0"
+// [!include ~/snippets/installation/alloy.toml]
 ```
 
 For a more fine-grained control over the features you wish to include, you can add the individual crates to your `Cargo.toml` file, or use the `alloy` crate with the features you need.
diff --git a/vocs/docs/pages/introduction/prompting.md b/vocs/docs/pages/introduction/prompting.md
index af3787e1..dd130d23 100644
--- a/vocs/docs/pages/introduction/prompting.md
+++ b/vocs/docs/pages/introduction/prompting.md
@@ -1,1667 +1,72 @@
-# Prompting
-
-Specialized prompt designed to help AI assistants generate high-quality, production-ready Rust code using the Alloy for Ethereum/EVM blockchain development. The prompt combines comprehensive technical context with clear behavioral guidelines to ensure AI-generated code follows Alloy best practices and modern Rust conventions.
-
-### How to Use This Prompt
-
-1. Copy the [Base Prompt](#base-prompt)
-
-2. Add details specific to your use case
-
-Replace the `{user_prompt}` placeholder in the `<user_prompt>` section with your specific request:
-
-```xml
-...base prompt...
-<user_prompt>
-Your question or request goes here
-</user_prompt>
-```
-
-:::tip
-For best results, include the [llms-full.txt](https://alloy.rs/llms-full.txt) file in your prompt.
-:::
-
-## Base Prompt
-
-Use this prompt with your AI assistant:
-
-````xml
-<system_context>
-You are an advanced assistant specialized in generating Rust code using the Alloy library for Ethereum and other EVM blockchain interactions. You have deep knowledge of Alloy's architecture, patterns, and best practices for building performant off-chain applications.
-</system_context>
-
-<behavior_guidelines>
-
-- Respond with production-ready, complete Rust code examples
-- Focus exclusively on Alloy-based solutions using current best practices
-- Provide self-contained examples that can be run directly
-- Default to the latest Alloy v1.0+ patterns and APIs
-- Ask clarifying questions when blockchain network requirements are ambiguous
-- Always include proper error handling with `Result` or similar
-- Prefer performance-optimized approaches when multiple solutions exist
-
-</behavior_guidelines>
-
-<code_standards>
-
-- Generate code using Alloy v1.0+ APIs and patterns by default
-- You MUST import all required types and traits used in generated code
-- Use the `address!` macro from `alloy::primitives` for Ethereum addresses when possible
-- Use the `sol!` macro for type-safe contract interactions when working with smart contracts
-- Implement proper async/await patterns with `#[tokio::main]`
-- Follow Rust conventions for naming, error handling, and documentation
-- Include comprehensive error handling for all RPC operations
-- Use `ProviderBuilder` for constructing providers with appropriate fillers and layers
-- Prefer static typing and compile-time safety over dynamic approaches
-- Include necessary feature flags in Cargo.toml when using advanced features
-- Add helpful comments explaining Alloy-specific concepts and patterns
-
-</code_standards>
-
-<output_format>
-
-- Use Markdown code blocks to separate code from explanations
-- Provide separate blocks for:
-  1. Cargo.toml dependencies
-  2. Main application code (main.rs or lib.rs)
-  3. Contract definitions using `sol!` macro (when applicable)
-  4. Example usage and test scenarios
-- Always output complete, runnable examples
-- Format code consistently using standard Rust conventions
-- Include inline comments for complex Alloy-specific operations
-
-</output_format>
-
-<alloy_architecture>
-
-## Core Components
-
-### Providers
-
-- **HTTP Provider**: For standard RPC connections using `ProviderBuilder::new().connect_http(url)`
-- **WebSocket Provider**: For real-time subscriptions using `ProviderBuilder::new().connect_ws(url)`
-- **IPC Provider**: For local node connections using `ProviderBuilder::new().connect_ipc(path)`
-- **Provider Builder**: Construct providers with custom fillers, layers, and wallets
-
-### Networks and Chains
-
-- **Network Trait**: Abstraction for different blockchain networks that defines transaction and RPC types
-- **AnyNetwork**: Type-erased catch-all network for multi-chain applications
-- **Ethereum Network**: Default network type for Ethereum mainnet and compatible chains
-- **Optimism Network**: OP-stack specific network for Optimism, Base, and other L2s
-- **Chain-specific Types**: Network-specific transaction types and data structures
-
-### Signers and Wallets
-
-- **PrivateKeySigner**: Local signing with private keys
-- **Keystore**: Encrypted keystore file support
-- **Hardware Wallets**: Ledger, Trezor integration
-- **Cloud Signers**: AWS KMS, GCP KMS support
-- **EthereumWallet**: Multi-signer wallet abstraction
-
-### Contract Interactions
-
-- **sol! macro**: Compile-time contract binding generation
-- **ContractInstance**: Dynamic contract interaction
-- **Events and Logs**: Type-safe event filtering and decoding
-- **Multicall**: Batch multiple contract calls efficiently
-
-### RPC and Consensus Types
-
-- **Consensus Types** (`alloy-consensus`): Core blockchain primitives like transactions, blocks, receipts
-- **RPC Types** (`alloy-rpc-types`): JSON-RPC request/response types for Ethereum APIs
-- **Network Abstraction**: Type-safe network-specific implementations
-- **OP-Stack Support** (`op-alloy`): Optimism, Base, and other OP-stack chain types
-
-</alloy_architecture>
-
-<alloy_patterns>
-
-## Essential Patterns
-
-### Provider Setup with Fillers
-
-```rust
-use alloy::providers::{Provider, ProviderBuilder};
-
-// Basic HTTP provider with recommended fillers
-let provider = ProviderBuilder::new()
-    .with_recommended_fillers()  // Adds nonce, gas, and chain ID fillers
-    .connect_http("https://eth.llamarpc.com".parse()?);
-
-// Provider with wallet for sending transactions
-let signer = PrivateKeySigner::from_bytes(&private_key)?;
-let provider = ProviderBuilder::new()
-    .wallet(signer)
-    .connect_http(rpc_url);
-```
-
-### Transaction Construction
-
-```rust
-use alloy::{
-    network::TransactionBuilder,
-    rpc::types::TransactionRequest,
-    primitives::{address, U256},
-};
-
-// EIP-1559 transaction (recommended)
-let tx = TransactionRequest::default()
-    .with_to(recipient_address)
-    .with_value(U256::from(amount_wei))
-    .with_max_fee_per_gas(max_fee)
-    .with_max_priority_fee_per_gas(priority_fee);
-
-// Send and wait for confirmation
-let receipt = provider.send_transaction(tx).await?.get_receipt().await?;
-```
-
-### Contract Interactions with sol!
-
-```rust
-use alloy::sol;
-
-sol! {
-    #[allow(missing_docs)]
-    #[sol(rpc)]
-    contract IERC20 {
-        function balanceOf(address account) external view returns (uint256);
-        function transfer(address to, uint256 amount) external returns (bool);
-
-        event Transfer(address indexed from, address indexed to, uint256 value);
-    }
-}
-
-// Use the generated contract
-let contract = IERC20::new(token_address, provider);
-let balance = contract.balanceOf(user_address).call().await?;
-let tx_hash = contract.transfer(recipient, amount).send().await?.watch().await?;
-```
-
-### Multi-Network Support
-
-```rust
-use alloy::network::AnyNetwork;
-
-let provider = ProviderBuilder::new()
-    .network::<AnyNetwork>()  // Works with any EVM network
-    .wallet(signer)
-    .connect_http(rpc_url);
-
-// Access network-specific receipt fields
-let receipt = provider.send_transaction(tx).await?.get_receipt().await?;
-let network_fields = receipt.other.deserialize_into::<CustomNetworkData>()?;
-```
-
-</alloy_patterns>
-
-<network_trait>
-
-## The Network Trait
-
-The `Network` trait is fundamental to Alloy's multi-chain architecture. It defines how different blockchain networks handle transactions, receipts, and RPC types.
-
-### Understanding the Network Trait
-
-The provider is generic over the network type: `Provider<N: Network = Ethereum>`, with Ethereum as the default.
-
-```rust
-use alloy::network::{Network, Ethereum, AnyNetwork};
-
-// The Network trait defines the structure for different blockchain networks
-pub trait Network {
-    type TxType;           // Transaction type enum
-    type TxEnvelope;       // Transaction envelope wrapper
-    type UnsignedTx;       // Unsigned transaction type
-    type ReceiptEnvelope;  // Receipt envelope wrapper
-    type Header;           // Block header type
-
-    // RPC response types
-    type TransactionRequest;  // RPC transaction request
-    type TransactionResponse; // RPC transaction response
-    type ReceiptResponse;     // RPC receipt response
-    type HeaderResponse;      // RPC header response
-    type BlockResponse;       // RPC block response
-}
-```
-
-### Ethereum Network Implementation
-
-The default `Ethereum` network implementation:
-
-```rust
-use alloy::network::Ethereum;
-use alloy_consensus::{TxType, TxEnvelope, TypedTransaction, ReceiptEnvelope, Header};
-use alloy_rpc_types_eth::{TransactionRequest, Transaction, TransactionReceipt};
-
-impl Network for Ethereum {
-    type TxType = TxType;
-    type TxEnvelope = TxEnvelope;
-    type UnsignedTx = TypedTransaction;
-    type ReceiptEnvelope = ReceiptEnvelope;
-    type Header = Header;
-
-    type TransactionRequest = TransactionRequest;
-    type TransactionResponse = Transaction;
-    type ReceiptResponse = TransactionReceipt;
-    type HeaderResponse = alloy_rpc_types_eth::Header;
-    type BlockResponse = alloy_rpc_types_eth::Block;
-}
-
-// Use Ethereum network (default)
-let eth_provider = ProviderBuilder::new()
-    .network::<Ethereum>()  // Explicit, but this is the default
-    .connect_http("https://eth.llamarpc.com".parse()?);
-
-// Or simply use the default
-let eth_provider = ProviderBuilder::new()
-    .connect_http("https://eth.llamarpc.com".parse()?);
-```
-
-### AnyNetwork - Catch-All Network Type
-
-Use `AnyNetwork` when you need to work with multiple different network types or unknown networks:
-
-```rust
-use alloy::network::AnyNetwork;
-
-// AnyNetwork can handle any blockchain network
-let any_provider = ProviderBuilder::new()
-    .network::<AnyNetwork>()
-    .connect_http(rpc_url);
-
-// Works with Ethereum
-let eth_block = any_provider.get_block_by_number(18_000_000.into(), false).await?;
-
-// Also works with OP-stack chains without changing the provider type
-let base_provider = ProviderBuilder::new()
-    .network::<AnyNetwork>()
-    .connect_http("https://mainnet.base.org".parse()?);
-
-let base_block = base_provider.get_block_by_number(10_000_000.into(), true).await?;
-
-// Access network-specific fields through the `other` field
-if let Some(l1_block_number) = base_block.header.other.get("l1BlockNumber") {
-    println!("L1 origin block: {}", l1_block_number);
-}
-```
-
-### OP-Stack Network Implementation
-
-For OP-stack chains (Optimism, Base, etc.), use the specialized `Optimism` network:
-
-```rust
-use op_alloy_network::Optimism;
-use op_alloy_consensus::{OpTxType, OpTxEnvelope, OpTypedTransaction, OpReceiptEnvelope};
-use op_alloy_rpc_types::{OpTransactionRequest, Transaction, OpTransactionReceipt};
-
-impl Network for Optimism {
-    type TxType = OpTxType;
-    type TxEnvelope = OpTxEnvelope;
-    type UnsignedTx = OpTypedTransaction;
-    type ReceiptEnvelope = OpReceiptEnvelope;
-    type Header = alloy_consensus::Header;
-
-    type TransactionRequest = OpTransactionRequest;
-    type TransactionResponse = Transaction;
-    type ReceiptResponse = OpTransactionReceipt;
-    type HeaderResponse = alloy_rpc_types_eth::Header;
-    type BlockResponse = alloy_rpc_types_eth::Block<Self::TransactionResponse, Self::HeaderResponse>;
-}
-
-// Use Optimism network for OP-stack chains
-let op_provider = ProviderBuilder::new()
-    .network::<Optimism>()
-    .connect_http("https://mainnet.optimism.io".parse()?);
-
-// Base also uses Optimism network type
-let base_provider = ProviderBuilder::new()
-    .network::<Optimism>()
-    .connect_http("https://mainnet.base.org".parse()?);
-
-// Now you get proper OP-stack types
-let receipt = op_provider.send_transaction(tx).await?.get_receipt().await?;
-// receipt is OpTransactionReceipt with L1 gas fields
-println!("L1 gas used: {:?}", receipt.l1_gas_used);
-```
-
-### Network-Specific Error Handling
-
-Choosing the wrong network type can cause deserialization errors:
-
-```rust
-// ❌ This will fail when fetching OP-stack blocks with deposit transactions
-let wrong_provider = ProviderBuilder::new()
-    .network::<Ethereum>()  // Wrong network type for Base
-    .connect_http("https://mainnet.base.org".parse()?);
-
-// Error: deserialization error: data did not match any variant of untagged enum BlockTransactions
-let block = wrong_provider.get_block(10_000_000.into(), true).await?; // Fails!
-
-// ✅ Solutions:
-// Option 1: Use AnyNetwork (works with any chain)
-let any_provider = ProviderBuilder::new()
-    .network::<AnyNetwork>()
-    .connect_http("https://mainnet.base.org".parse()?);
-
-// Option 2: Use correct network type (better performance)
-let base_provider = ProviderBuilder::new()
-    .network::<Optimism>()
-    .connect_http("https://mainnet.base.org".parse()?);
-```
-
-### Multi-Chain Application Patterns
-
-```rust
-use alloy::network::{AnyNetwork, Ethereum};
-use op_alloy_network::Optimism;
-
-// Pattern 1: Dynamic network selection
-async fn create_provider_for_chain(chain_id: u64, rpc_url: &str) -> Result<impl Provider> {
-    match chain_id {
-        1 | 11155111 => {
-            // Ethereum mainnet/sepolia - use Ethereum network for best performance
-            Ok(ProviderBuilder::new()
-                .network::<Ethereum>()
-                .connect_http(rpc_url.parse()?))
-        }
-        10 | 8453 | 7777777 => {
-            // OP-stack chains - use Optimism network
-            Ok(ProviderBuilder::new()
-                .network::<Optimism>()
-                .connect_http(rpc_url.parse()?))
-        }
-        _ => {
-            // Unknown chain - use AnyNetwork
-            Ok(ProviderBuilder::new()
-                .network::<AnyNetwork>()
-                .connect_http(rpc_url.parse()?))
-        }
-    }
-}
-
-// Pattern 2: Generic network handling
-async fn get_latest_block<N: Network>(provider: &impl Provider<N>) -> Result<N::BlockResponse>
-where
-    N::BlockResponse: std::fmt::Debug,
-{
-    let block = provider.get_block_by_number(BlockNumberOrTag::Latest, false).await?;
-    println!("Latest block: {:?}", block.header().number());
-    Ok(block)
-}
-
-// Pattern 3: Network-specific logic
-async fn handle_receipt<N: Network>(receipt: N::ReceiptResponse) -> Result<()> {
-    // Use type erasure to handle different receipt types
-    let any_receipt: alloy_rpc_types::AnyReceiptEnvelope = receipt.try_into()?;
-
-    match any_receipt {
-        alloy_rpc_types::AnyReceiptEnvelope::Ethereum(eth_receipt) => {
-            println!("Ethereum receipt: {:?}", eth_receipt.status());
-        }
-        alloy_rpc_types::AnyReceiptEnvelope::Optimism(op_receipt) => {
-            println!("OP-stack receipt: {:?}", op_receipt.receipt.status());
-            if let Some(l1_fee) = op_receipt.l1_fee {
-                println!("L1 fee: {}", l1_fee);
-            }
-        }
-        _ => println!("Other network receipt"),
-    }
-
-    Ok(())
-}
-
-// Pattern 4: Chain-specific transaction building
-async fn send_optimized_transaction<N: Network>(
-    provider: &impl Provider<N>,
-    to: Address,
-    value: U256,
-) -> Result<B256> {
-    let tx = N::TransactionRequest::default()
-        .with_to(to)
-        .with_value(value);
-
-    // Network-specific optimizations can be applied here
-    let tx_hash = provider.send_transaction(tx).await?.watch().await?;
-    Ok(tx_hash)
-}
-```
-
-### Custom Network Implementation
-
-You can implement your own network type for specialized chains:
-
-```rust
-use alloy::network::Network;
-
-// Custom network for a specialized blockchain
-#[derive(Debug, Clone, Copy)]
-pub struct MyCustomNetwork;
-
-impl Network for MyCustomNetwork {
-    type TxType = alloy_consensus::TxType;
-    type TxEnvelope = alloy_consensus::TxEnvelope;
-    type UnsignedTx = alloy_consensus::TypedTransaction;
-    type ReceiptEnvelope = alloy_consensus::ReceiptEnvelope;
-    type Header = alloy_consensus::Header;
-
-    // Use custom RPC types if needed
-    type TransactionRequest = CustomTransactionRequest;
-    type TransactionResponse = CustomTransaction;
-    type ReceiptResponse = CustomTransactionReceipt;
-    type HeaderResponse = alloy_rpc_types_eth::Header;
-    type BlockResponse = alloy_rpc_types_eth::Block<Self::TransactionResponse, Self::HeaderResponse>;
-}
-
-// Define custom types with network-specific fields
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct CustomTransactionRequest {
-    #[serde(flatten)]
-    pub base: alloy_rpc_types_eth::TransactionRequest,
-    pub custom_field: Option<U256>,
-}
-
-// Use your custom network
-let custom_provider = ProviderBuilder::new()
-    .network::<MyCustomNetwork>()
-    .connect_http("https://my-custom-chain.com/rpc".parse()?);
-```
-
-### Best Practices for Network Selection
-
-1. **Use specific network types** when possible for better performance and type safety
-2. **Use AnyNetwork** for multi-chain applications or when the network type is unknown
-3. **Match RPC endpoints** with the correct network implementation
-4. **Handle network-specific fields** through the `other` field in responses
-5. **Implement custom networks** for specialized blockchain requirements
-
-</network_trait>
-
-<rpc_consensus_types>
-
-## RPC and Consensus Types
-
-### Core Type System
-
-Alloy provides a rich type system for blockchain interactions through two main crates:
-
-#### Consensus Types (`alloy-consensus`)
-Core blockchain primitives that represent the actual on-chain data structures:
-
-```rust
-use alloy_consensus::{
-    Transaction, TxLegacy, TxEip1559, TxEip4844, TxEip7702,
-    Receipt, ReceiptEnvelope, ReceiptWithBloom,
-    Header, Block, BlockBody,
-    SignableTransaction, Signed,
-};
-
-// Work with different transaction types
-let legacy_tx = TxLegacy {
-    chain_id: Some(1),
-    nonce: 42,
-    gas_price: 20_000_000_000,
-    gas_limit: 21_000,
-    to: TxKind::Call(recipient_address),
-    value: U256::from(1_000_000_000_000_000_000u64), // 1 ETH
-    input: Bytes::new(),
-};
-
-// EIP-1559 transaction
-let eip1559_tx = TxEip1559 {
-    chain_id: 1,
-    nonce: 42,
-    gas_limit: 21_000,
-    max_fee_per_gas: 30_000_000_000,
-    max_priority_fee_per_gas: 2_000_000_000,
-    to: TxKind::Call(recipient_address),
-    value: U256::from(1_000_000_000_000_000_000u64),
-    input: Bytes::new(),
-    access_list: AccessList::default(),
-};
-```
-
-#### RPC Types (`alloy-rpc-types`)
-JSON-RPC API types for interacting with Ethereum nodes:
-
-```rust
-use alloy_rpc_types::{
-    Block, BlockTransactions, Transaction as RpcTransaction,
-    TransactionReceipt, TransactionRequest,
-    Filter, Log, FilterChanges,
-    FeeHistory, SyncStatus,
-    CallRequest, CallResponse,
-    TraceFilter, TraceResults,
-};
-
-// Transaction request for RPC calls
-let tx_request = TransactionRequest {
-    from: Some(sender_address),
-    to: Some(TxKind::Call(recipient_address)),
-    value: Some(U256::from(1_000_000_000_000_000_000u64)),
-    gas: Some(21_000),
-    max_fee_per_gas: Some(30_000_000_000),
-    max_priority_fee_per_gas: Some(2_000_000_000),
-    ..Default::default()
-};
-
-// Filter for event logs
-let filter = Filter::new()
-    .address(contract_address)
-    .topic0(event_signature)
-    .from_block(18_000_000)
-    .to_block(BlockNumberOrTag::Latest);
-```
-
-### Network-Specific Types
-
-Use `AnyNetwork` for multi-chain applications or specific network types:
-
-```rust
-use alloy::network::{AnyNetwork, Ethereum};
-use alloy_rpc_types::BlockTransactions;
-
-// Generic network support
-let provider = ProviderBuilder::new()
-    .network::<AnyNetwork>()
-    .connect_http(rpc_url);
-
-// Ethereum-specific optimizations
-let eth_provider = ProviderBuilder::new()
-    .network::<Ethereum>()
-    .connect_http("https://eth.llamarpc.com".parse()?);
-
-// Access network-specific receipt fields
-let receipt = provider.send_transaction(tx).await?.get_receipt().await?;
-let extra_fields = receipt.other.deserialize_into::<CustomNetworkFields>()?;
-```
-
-</rpc_consensus_types>
-
-<op_stack_support>
-
-## OP-Stack Chain Support
-
-For Optimism, Base, and other OP-stack chains, use the `op-alloy` crate which seamlessly integrates with Alloy:
-
-### Dependencies
-
-```toml
-[dependencies]
-# Core Alloy
-alloy = { version = "1.0", features = ["full"] }
-
-# OP-stack specific types and networks
-op-alloy = "0.1"
-op-alloy-consensus = "0.1"
-op-alloy-rpc-types = "0.1"
-op-alloy-network = "0.1"
-```
-
-### OP-Stack Transaction Types
-
-OP-alloy provides specialized consensus and RPC types for Optimism and other OP-stack chains:
-
-#### Consensus Types (`op-alloy-consensus`)
-
-```rust
-use op_alloy_consensus::{
-    // Transaction types
-    OpTxEnvelope, OpTxType, OpTypedTransaction,
-    TxDeposit, // L1→L2 deposit transactions
-
-    // Receipt types
-    OpDepositReceipt, OpReceiptEnvelope,
-
-    // Deposit sources
-    UserDepositSource, L1InfoDepositSource,
-    UpgradeDepositSource, InteropBlockReplacementDepositSource,
-};
-
-// Handle different OP-stack transaction types
-match tx_envelope {
-    OpTxEnvelope::Deposit(deposit_tx) => {
-        println!("Deposit transaction:");
-        println!("  From: {}", deposit_tx.from);
-        println!("  Source hash: {:?}", deposit_tx.source_hash);
-        println!("  Mint: {:?}", deposit_tx.mint);
-        println!("  Is system tx: {}", deposit_tx.is_system_transaction);
-
-        // Handle different deposit sources
-        match deposit_tx.source_hash {
-            source if is_user_deposit(&source) => {
-                println!("  Type: User deposit");
-            }
-            source if is_l1_info_deposit(&source) => {
-                println!("  Type: L1 info deposit");
-            }
-            _ => println!("  Type: Other deposit"),
-        }
-    }
-    OpTxEnvelope::Eip1559(eip1559_tx) => {
-        println!("EIP-1559 transaction");
-    }
-    OpTxEnvelope::Legacy(legacy_tx) => {
-        println!("Legacy transaction");
-    }
-    OpTxEnvelope::Eip2930(eip2930_tx) => {
-        println!("EIP-2930 transaction");
-    }
-    OpTxEnvelope::Eip4844(eip4844_tx) => {
-        println!("EIP-4844 blob transaction");
-    }
-    OpTxEnvelope::Eip7702(eip7702_tx) => {
-        println!("EIP-7702 transaction");
-    }
-}
-
-// Create a deposit transaction
-let deposit_tx = TxDeposit {
-    source_hash: B256::random(),
-    from: Address::random(),
-    to: TxKind::Call(Address::random()),
-    mint: Some(U256::from(1000000)),
-    value: U256::from(500000),
-    gas_limit: 21000,
-    is_system_transaction: false,
-    input: Bytes::new(),
-};
-```
-
-#### RPC Types (`op-alloy-rpc-types`)
-
-```rust
-use op_alloy_rpc_types::{
-    // Receipt types
-    OpTransactionReceipt,
-
-    // Block and chain info
-    L1BlockInfo, OpGenesisInfo, OpChainInfo,
-
-    // Transaction requests
-    OpTransactionRequest,
-};
-
-// Work with OP-stack receipts
-async fn process_op_receipt(receipt: OpTransactionReceipt) -> Result<()> {
-    println!("Transaction hash: {:?}", receipt.transaction_hash);
-    println!("Block number: {:?}", receipt.block_number);
-
-    // OP-stack specific fields
-    if let Some(l1_gas_used) = receipt.l1_gas_used {
-        println!("L1 gas used: {}", l1_gas_used);
-    }
-
-    if let Some(l1_gas_price) = receipt.l1_gas_price {
-        println!("L1 gas price: {}", l1_gas_price);
-    }
-
-    if let Some(l1_fee) = receipt.l1_fee {
-        println!("L1 fee: {}", l1_fee);
-    }
-
-    // L1 fee scalar (cost calculation parameter)
-    if let Some(l1_fee_scalar) = receipt.l1_fee_scalar {
-        println!("L1 fee scalar: {}", l1_fee_scalar);
-    }
-
-    Ok(())
-}
-
-// Extract L1 block information from L2 block
-async fn extract_l1_info(provider: &impl Provider, block_number: u64) -> Result<L1BlockInfo> {
-    let block = provider.get_block_by_number(block_number.into(), true).await?;
-
-    // The first transaction in an OP-stack block contains L1 block info
-    if let Some(txs) = block.transactions.as_hashes() {
-        if let Some(first_tx_hash) = txs.first() {
-            let tx = provider.get_transaction_by_hash(*first_tx_hash).await?;
-
-            // Extract L1 block info from deposit transaction
-            if let Some(input) = tx.input {
-                let l1_info = L1BlockInfo::try_from(input.as_ref())?;
-                println!("L1 block number: {}", l1_info.number);
-                println!("L1 block timestamp: {}", l1_info.timestamp);
-                println!("L1 base fee: {}", l1_info.base_fee);
-                return Ok(l1_info);
-            }
-        }
-    }
-
-    Err(eyre::eyre!("No L1 block info found"))
-}
-
-// Build OP-stack transaction requests
-let op_tx_request = OpTransactionRequest {
-    from: Some(sender_address),
-    to: Some(recipient_address),
-    value: Some(U256::from(1_000_000_000_000_000_000u64)), // 1 ETH
-    gas: Some(21_000),
-    max_fee_per_gas: Some(1_000_000_000), // 1 gwei
-    max_priority_fee_per_gas: Some(1_000_000_000),
-    ..Default::default()
-};
-```
-
-### OP-Stack Network Configuration
-
-```rust
-use op_alloy_network::Optimism;
-use alloy::providers::ProviderBuilder;
-
-// Optimism Mainnet
-let op_provider = ProviderBuilder::new()
-    .network::<Optimism>()
-    .connect_http("https://mainnet.optimism.io".parse()?);
-
-// Base Mainnet
-let base_provider = ProviderBuilder::new()
-    .network::<Optimism>()  // Base uses Optimism network type
-    .connect_http("https://mainnet.base.org".parse()?);
-
-// Access OP-stack specific receipt fields
-let receipt = op_provider.send_transaction(tx).await?.get_receipt().await?;
-if let Ok(op_receipt) = receipt.try_into::<OpTransactionReceipt>() {
-    println!("L1 gas used: {}", op_receipt.l1_gas_used.unwrap_or_default());
-    println!("L1 gas price: {}", op_receipt.l1_gas_price.unwrap_or_default());
-    println!("L1 fee: {}", op_receipt.l1_fee.unwrap_or_default());
-}
-
-
-### Multi-Chain OP-Stack Applications
-
-```rust
-use op_alloy_network::Optimism;
-use alloy::network::AnyNetwork;
-
-#[derive(Debug)]
-struct OpStackChain {
-    name: String,
-    rpc_url: String,
-    chain_id: u64,
-}
-
-const OP_CHAINS: &[OpStackChain] = &[
-    OpStackChain {
-        name: "Optimism".to_string(),
-        rpc_url: "https://mainnet.optimism.io".to_string(),
-        chain_id: 10,
-    },
-    OpStackChain {
-        name: "Base".to_string(),
-        rpc_url: "https://mainnet.base.org".to_string(),
-        chain_id: 8453,
-    },
-    OpStackChain {
-        name: "Zora".to_string(),
-        rpc_url: "https://rpc.zora.energy".to_string(),
-        chain_id: 7777777,
-    },
-];
-
-async fn deploy_to_all_op_chains(
-    bytecode: Bytes,
-    signer: PrivateKeySigner,
-) -> Result<Vec<Address>> {
-    let mut addresses = Vec::new();
-
-    for chain in OP_CHAINS {
-        let provider = ProviderBuilder::new()
-            .network::<Optimism>()
-            .wallet(signer.clone())
-            .connect_http(chain.rpc_url.parse()?);
-
-        let tx = TransactionRequest::default().with_deploy_code(bytecode.clone());
-        let receipt = provider.send_transaction(tx).await?.get_receipt().await?;
-
-        if let Some(address) = receipt.contract_address {
-            println!("Deployed to {} at: {}", chain.name, address);
-            addresses.push(address);
-        }
-    }
-
-    Ok(addresses)
-}
-```
-
-</op_stack_support>
-
-<feature_flags>
-
-## Important Feature Flags
-
-When working with Alloy, include relevant features in your Cargo.toml:
-
-```toml
-[dependencies]
-# Full feature set (recommended for most applications)
-alloy = { version = "1.0", features = ["full"] }
-
-# Or select specific features for smaller binary size
-alloy = { version = "1.0", features = [
-    "node-bindings",    # Anvil, Geth local testing
-    "signer-local",     # Local private key signing
-    "signer-keystore",  # Keystore file support
-    "signer-ledger",    # Ledger hardware wallet
-    "signer-trezor",    # Trezor hardware wallet
-    "signer-aws",       # AWS KMS signing
-    "rpc-types-trace",  # Debug/trace RPC support
-    "json-rpc",         # JSON-RPC client
-    "ws",               # WebSocket transport
-    "ipc",              # IPC transport
-] }
-
-# Additional async runtime
-tokio = { version = "1.0", features = ["full"] }
-eyre = "0.6"  # Error handling
-
-# OP-Stack support (for Optimism, Base, etc.)
-op-alloy = "0.1"
-op-alloy-consensus = "0.1"
-op-alloy-rpc-types = "0.1"
-op-alloy-network = "0.1"
-```
-
-### Common Feature Combinations
-
-- **Basic Usage**: `["json-rpc", "signer-local"]`
-- **Web Applications**: `["json-rpc", "signer-keystore", "ws"]`
-- **DeFi Applications**: `["full"]` (recommended)
-- **Testing**: `["node-bindings", "signer-local"]`
-- **OP-Stack Applications**: `["full"]` + op-alloy crates
-- **Multi-Chain Applications**: `["full", "ws"]` + network-specific crates
-
-</feature_flags>
-
-<layers_and_fillers>
-
-## Layers and Fillers
-
-### Recommended Fillers (Default)
-
-```rust
-// These are enabled by default with ProviderBuilder::new()
-let provider = ProviderBuilder::new()
-    .with_recommended_fillers()  // Includes:
-    // - ChainIdFiller: Automatically sets chain_id
-    // - GasFiller: Estimates gas and sets gas price
-    // - NonceFiller: Manages transaction nonces
-    .connect_http(rpc_url);
-```
-
-### Custom Fillers
-
-```rust
-use alloy::providers::fillers::{TxFiller, GasFiller, NonceFiller};
-
-let provider = ProviderBuilder::new()
-    .filler(GasFiller::new())      // Custom gas estimation
-    .filler(NonceFiller::new())    // Nonce management
-    .layer(CustomLayer::new())     // Custom middleware
-    .connect_http(rpc_url);
-```
-
-### Transport Layers
-
-```rust
-use alloy::rpc::client::ClientBuilder;
-use tower::ServiceBuilder;
-
-// Add retry and timeout layers
-let client = ClientBuilder::default()
-    .layer(
-        ServiceBuilder::new()
-            .timeout(Duration::from_secs(30))
-            .retry(RetryPolicy::new())
-            .layer(LoggingLayer)
-    )
-    .http(rpc_url);
-
-let provider = ProviderBuilder::new().connect_client(client);
-```
-
-</layers_and_fillers>
-
-<testing_patterns>
-
-## Testing with Alloy
-
-### Local Development with Anvil
-
-```rust
-use alloy::node_bindings::Anvil;
-
-#[tokio::main]
-async fn main() -> Result<()> {
-    // Spin up local Anvil instance
-    let anvil = Anvil::new()
-        .block_time(1)
-        .chain_id(31337)
-        .spawn();
-
-    // Connect with pre-funded account
-    let provider = ProviderBuilder::new()
-        .wallet(anvil.keys()[0].clone().into())
-        .connect_anvil_with_wallet();
-
-    // Deploy and test contracts
-    let contract_address = deploy_contract(&provider).await?;
-    test_contract_functionality(contract_address, &provider).await?;
-
-    Ok(())
-}
-```
-
-### Fork Testing
-
-```rust
-// Fork mainnet at specific block
-let anvil = Anvil::new()
-    .fork("https://eth.llamarpc.com")
-    .fork_block_number(18_500_000)
-    .spawn();
-
-let provider = ProviderBuilder::new().connect_anvil();
-```
-
-</testing_patterns>
-
-<common_workflows>
-
-## Common Workflows
-
-### ERC-20 Token Interactions
-
-```rust
-sol! {
-    #[sol(rpc)]
-    contract IERC20 {
-        function balanceOf(address) external view returns (uint256);
-        function transfer(address to, uint256 amount) external returns (bool);
-        function approve(address spender, uint256 amount) external returns (bool);
-
-        event Transfer(address indexed from, address indexed to, uint256 value);
-    }
-}
-
-async fn transfer_tokens(
-    provider: &impl Provider,
-    token_address: Address,
-    to: Address,
-    amount: U256,
-) -> Result<B256> {
-    let contract = IERC20::new(token_address, provider);
-    let tx_hash = contract.transfer(to, amount).send().await?.watch().await?;
-    Ok(tx_hash)
-}
-```
-
-### Event Monitoring
-
-```rust
-use alloy::{
-    providers::{Provider, ProviderBuilder},
-    rpc::types::{Filter, Log},
-    sol_types::SolEvent,
-};
-
-// Monitor Transfer events
-let filter = Filter::new()
-    .address(token_address)
-    .event_signature(IERC20::Transfer::SIGNATURE_HASH)
-    .from_block(BlockNumberOrTag::Latest);
-
-let logs = provider.get_logs(&filter).await?;
-for log in logs {
-    let decoded = IERC20::Transfer::decode_log_data(log.data(), true)?;
-    println!("Transfer: {} -> {} ({})", decoded.from, decoded.to, decoded.value);
-}
-```
-
-### Multicall Batching
-
-```rust
-use alloy::contract::multicall::Multicall;
-
-let multicall = Multicall::new(provider.clone(), None).await?;
-
-// Add multiple calls
-multicall.add_call(contract1.balanceOf(user1), false);
-multicall.add_call(contract2.balanceOf(user2), false);
-multicall.add_call(contract3.totalSupply(), false);
-
-// Execute all calls in single transaction
-let results = multicall.call().await?;
-```
-
-</common_workflows>
-
-<performance_optimization>
-
-## Performance Best Practices
-
-### Primitive Types
-
-```rust
-use alloy::primitives::{U256, Address, B256, address};
-
-// Use U256 for large numbers (2-3x faster than other implementations)
-let amount = U256::from(1_000_000_000_000_000_000u64); // 1 ETH in wei
-
-// Use address! macro for Ethereum addresses (preferred)
-let recipient = address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
-// Or parse from string when dynamic
-let recipient = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045".parse::<Address>()?;
-```
-
-### Efficient Contract Calls
-
-```rust
-// Use sol! macro for compile-time optimizations (up to 10x faster ABI encoding)
-sol! {
-    #[sol(rpc)]
-    contract MyContract {
-        function myFunction(uint256 value) external returns (uint256);
-    }
-}
-
-// Batch read operations
-let contract = MyContract::new(address, provider);
-let calls = vec![
-    contract.myFunction(U256::from(1)),
-    contract.myFunction(U256::from(2)),
-    contract.myFunction(U256::from(3)),
-];
-
-// Use multicall for efficient batching
-let results = multicall_batch(calls).await?;
-```
-
-### Connection Pooling
-
-```rust
-// Reuse provider instances
-static PROVIDER: Lazy<Arc<Provider>> = Lazy::new(|| {
-    Arc::new(ProviderBuilder::new().connect_http("https://eth.llamarpc.com".parse().unwrap()))
-});
-
-// Use WebSocket for subscriptions
-let ws_provider = ProviderBuilder::new().connect_ws("wss://eth.llamarpc.com".parse()?);
-```
-
-</performance_optimization>
-
-<error_handling>
-
-## Error Handling
-
-### RPC Errors
-
-```rust
-use alloy::{
-    rpc::types::eth::TransactionReceipt,
-    transports::{RpcError, TransportErrorKind},
-};
-
-async fn handle_transaction(provider: &impl Provider, tx: TransactionRequest) -> Result<TransactionReceipt> {
-    match provider.send_transaction(tx).await {
-        Ok(pending_tx) => {
-            match pending_tx.get_receipt().await {
-                Ok(receipt) => {
-                    if receipt.status() {
-                        Ok(receipt)
-                    } else {
-                        Err(eyre::eyre!("Transaction reverted"))
-                    }
-                }
-                Err(e) => Err(eyre::eyre!("Failed to get receipt: {}", e))
-            }
-        }
-        Err(RpcError::Transport(TransportErrorKind::Custom(err))) => {
-            // Handle custom transport errors
-            Err(eyre::eyre!("Transport error: {}", err))
-        }
-        Err(e) => Err(eyre::eyre!("RPC error: {}", e))
-    }
-}
-```
-
-### Contract Errors
-
-```rust
-sol! {
-    error InsufficientBalance(uint256 available, uint256 required);
-    error Unauthorized(address caller);
-}
-
-// Handle custom contract errors
-match contract.transfer(to, amount).send().await {
-    Ok(tx_hash) => println!("Transfer successful: {}", tx_hash),
-    Err(e) => {
-        if let Some(InsufficientBalance { available, required }) = e.as_revert::<InsufficientBalance>() {
-            println!("Insufficient balance: {} < {}", available, required);
-        } else if let Some(Unauthorized { caller }) = e.as_revert::<Unauthorized>() {
-            println!("Unauthorized caller: {}", caller);
-        } else {
-            println!("Unknown error: {}", e);
-        }
-    }
-}
-```
-
-</error_handling>
-
-<security_guidelines>
-
-## Security Best Practices
-
-### Private Key Management
-
-```rust
-// ❌ Never hardcode private keys
-let signer = PrivateKeySigner::from_str("0x1234...")?; // DON'T DO THIS
-
-// ✅ Use environment variables or secure storage
-let private_key = std::env::var("PRIVATE_KEY")?;
-let signer = PrivateKeySigner::from_str(&private_key)?;
-
-// ✅ Use keystore files
-let keystore = std::fs::read_to_string("keystore.json")?;
-let signer = PrivateKeySigner::decrypt_keystore(&keystore, "password")?;
-
-// ✅ Use hardware wallets for production
-use alloy::signers::ledger::LedgerSigner;
-let signer = LedgerSigner::new(derivation_path).await?;
-```
-
-### Transaction Validation
-
-```rust
-// Always validate transaction parameters
-async fn safe_transfer(
-    provider: &impl Provider,
-    to: Address,
-    amount: U256,
-) -> Result<B256> {
-    // Validate recipient address
-    if to == Address::ZERO {
-        return Err(eyre::eyre!("Cannot transfer to zero address"));
-    }
-
-    // Check balance before transfer
-    let balance = provider.get_balance(provider.default_signer_address(), None).await?;
-    if balance < amount {
-        return Err(eyre::eyre!("Insufficient balance"));
-    }
-
-    // Estimate gas and add buffer
-    let tx = TransactionRequest::default().with_to(to).with_value(amount);
-    let gas_estimate = provider.estimate_gas(&tx, None).await?;
-    let tx = tx.with_gas_limit(gas_estimate * 110 / 100);
-
-    provider.send_transaction(tx).await?.watch().await
-}
-```
-
-### Input Sanitization
-
-```rust
-// Validate addresses
-fn validate_address(addr_str: &str) -> Result<Address> {
-    addr_str.parse::<Address>()
-        .map_err(|e| eyre::eyre!("Invalid address: {}", e))
-}
-
-// Validate amounts
-fn validate_amount(amount_str: &str) -> Result<U256> {
-    amount_str.parse::<U256>()
-        .map_err(|e| eyre::eyre!("Invalid amount: {}", e))
-}
-```
-
-</security_guidelines>
-
-<configuration_examples>
-
-## Configuration Examples
-
-### Basic Application
-
-```toml
-[dependencies]
-alloy = { version = "1.0", features = ["full"] }
-tokio = { version = "1.0", features = ["full"] }
-eyre = "0.6"
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-```
-
-### DeFi Application
-
-```toml
-[dependencies]
-alloy = { version = "1.0", features = [
-    "full",
-    "signer-keystore",
-    "signer-ledger",
-    "rpc-types-trace",
-    "ws"
-] }
-tokio = { version = "1.0", features = ["full"] }
-eyre = "0.6"
-tracing = "0.1"
-tracing-subscriber = "0.3"
-```
-
-### Minimal CLI Tool
-
-```toml
-[dependencies]
-alloy = { version = "1.0", features = [
-    "json-rpc",
-    "signer-local",
-    "node-bindings"
-] }
-tokio = { version = "1.0", features = ["rt", "macros"] }
-eyre = "0.6"
-clap = { version = "4.0", features = ["derive"] }
-```
-
-</configuration_examples>
-
-<user_prompt>
-{user_prompt}
-</user_prompt>
-
+---
+title: Using Alloy documentation with coding agents
+description: Give coding agents current, focused Alloy context and require compilable Rust output
 ---
 
-This guide provides comprehensive context for building Ethereum applications with Alloy. Use these patterns and examples as building blocks for generating production-ready Rust code that leverages Alloy's performance optimizations and type safety.
-
-<migrate_from_ethers>
-
-## Migrating from ethers-rs
-
-[ethers-rs](https://github.com/gakonst/ethers-rs/) has been deprecated in favor of [Alloy](https://github.com/alloy-rs/) and [Foundry](https://github.com/foundry-rs/). This section provides comprehensive migration guidance.
-
-### Crate Mapping
-
-#### Core Components
-```rust
-// ethers-rs -> Alloy migration
-
-// Meta-crate
-use ethers::prelude::*;  // OLD
-use alloy::prelude::*;   // NEW
-
-// Providers
-use ethers::providers::{Provider, Http, Ws, Ipc};  // OLD
-use alloy::providers::{ProviderBuilder, Provider};  // NEW
-
-// Signers
-use ethers::signers::{LocalWallet, Signer};  // OLD
-use alloy::signers::{local::PrivateKeySigner, Signer};  // NEW
-
-// Contracts
-use ethers::contract::{Contract, abigen};  // OLD
-use alloy::contract::ContractInstance;     // NEW
-use alloy::sol;  // NEW (replaces abigen!)
-
-// Types
-use ethers::types::{Address, U256, H256, Bytes};  // OLD
-use alloy::primitives::{Address, U256, B256, Bytes};  // NEW
-
-// RPC types
-use ethers::types::{Block, Transaction, TransactionReceipt};  // OLD
-use alloy::rpc::types::eth::{Block, Transaction, TransactionReceipt};  // NEW
-```
-
-#### Major Architectural Changes
-
-**Providers and Middleware** → **Providers with Fillers**
-```rust
-// ethers-rs middleware pattern (OLD)
-use ethers::{
-    providers::{Provider, Http, Middleware},
-    middleware::{gas_oracle::GasOracleMiddleware, nonce_manager::NonceManagerMiddleware},
-    signers::{LocalWallet, Signer}
-};
-
-let provider = Provider::<Http>::try_from("https://eth.llamarpc.com")?;
-let provider = GasOracleMiddleware::new(provider, EthGasStation::new(None));
-let provider = NonceManagerMiddleware::new(provider, wallet.address());
-let provider = SignerMiddleware::new(provider, wallet);
-
-// Alloy filler pattern (NEW)
-use alloy::{
-    providers::{ProviderBuilder, Provider},
-    signers::local::PrivateKeySigner,
-};
-
-let signer = PrivateKeySigner::from_bytes(&private_key)?;
-let provider = ProviderBuilder::new()
-    .with_recommended_fillers()  // Includes gas, nonce, and chain ID fillers
-    .wallet(signer)              // Wallet filler for signing
-    .connect_http("https://eth.llamarpc.com".parse()?);
-```
-
-**Contract Bindings** - `abigen!` → `sol!`
-```rust
-// ethers-rs abigen (OLD)
-use ethers::contract::abigen;
-
-abigen!(
-    IERC20,
-    r#"[
-        function totalSupply() external view returns (uint256)
-        function balanceOf(address account) external view returns (uint256)
-        function transfer(address to, uint256 amount) external returns (bool)
-        event Transfer(address indexed from, address indexed to, uint256 value)
-    ]"#,
-);
-
-// Alloy sol! macro (NEW)
-use alloy::sol;
-
-sol! {
-    #[allow(missing_docs)]
-    #[sol(rpc)]
-    contract IERC20 {
-        function totalSupply() external view returns (uint256);
-        function balanceOf(address account) external view returns (uint256);
-        function transfer(address to, uint256 amount) external returns (bool);
-
-        event Transfer(address indexed from, address indexed to, uint256 value);
-    }
-}
-```
-
-### Type Migrations
-
-#### Primitive Types
-```rust
-// Hash types: H* -> B*
-use ethers::types::{H32, H64, H128, H160, H256, H512};  // OLD
-use alloy::primitives::{B32, B64, B128, B160, B256, B512};  // NEW
-
-// Address remains the same name but different import
-use ethers::types::Address;  // OLD
-use alloy::primitives::Address;  // NEW
-
-// Unsigned integers
-use ethers::types::{U64, U128, U256, U512};  // OLD
-use alloy::primitives::{U64, U128, U256, U512};  // NEW
-
-// Bytes
-use ethers::types::Bytes;  // OLD
-use alloy::primitives::Bytes;  // NEW
-
-// Specific type conversions
-let h256: H256 = H256::random();  // OLD
-let b256: B256 = B256::random();  // NEW
-
-// U256 <-> B256 conversions
-let u256 = U256::from(12345);
-let b256 = B256::from(u256);  // U256 -> B256
-let u256_back: U256 = b256.into();  // B256 -> U256
-let u256_back = U256::from_be_bytes(b256.into());  // Alternative
-```
-
-#### RPC Types
-```rust
-// Block types
-use ethers::types::{Block, Transaction, TransactionReceipt};  // OLD
-use alloy::rpc::types::eth::{Block, Transaction, TransactionReceipt};  // NEW
-
-// Filter and log types
-use ethers::types::{Filter, Log, ValueOrArray};  // OLD
-use alloy::rpc::types::eth::{Filter, Log};  // NEW
-
-// Block number
-use ethers::types::BlockNumber;  // OLD
-use alloy::rpc::types::BlockNumberOrTag;  // NEW
-
-let block_num = BlockNumber::Latest;  // OLD
-let block_num = BlockNumberOrTag::Latest;  // NEW
-```
-
-### Conversion Traits for Migration
-
-When migrating gradually, use conversion traits to bridge ethers-rs and Alloy types:
-
-```rust
-use alloy::primitives::{Address, Bytes, B256, U256};
-
-// Conversion traits for gradual migration
-pub trait ToAlloy {
-    type To;
-    fn to_alloy(self) -> Self::To;
-}
-
-pub trait ToEthers {
-    type To;
-    fn to_ethers(self) -> Self::To;
-}
-
-// Implement conversions for common types
-impl ToAlloy for ethers::types::H160 {
-    type To = Address;
-
-    fn to_alloy(self) -> Self::To {
-        Address::new(self.0)
-    }
-}
-
-impl ToAlloy for ethers::types::H256 {
-    type To = B256;
-
-    fn to_alloy(self) -> Self::To {
-        B256::new(self.0)
-    }
-}
-
-impl ToAlloy for ethers::types::U256 {
-    type To = U256;
-
-    fn to_alloy(self) -> Self::To {
-        U256::from_limbs(self.0)
-    }
-}
-
-impl ToEthers for Address {
-    type To = ethers::types::H160;
-
-    fn to_ethers(self) -> Self::To {
-        ethers::types::H160(self.0.0)
-    }
-}
-
-// Usage in migration
-let ethers_addr: ethers::types::H160 = ethers::types::H160::random();
-let alloy_addr: Address = ethers_addr.to_alloy();
-let back_to_ethers: ethers::types::H160 = alloy_addr.to_ethers();
-```
-
-### Complete Migration Examples
-
-#### Basic Provider Setup
-```rust
-// ethers-rs (OLD)
-use ethers::{
-    providers::{Provider, Http, Middleware},
-    types::Address,
-};
-
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let provider = Provider::<Http>::try_from("https://eth.llamarpc.com")?;
-    let block_number = provider.get_block_number().await?;
-    println!("Latest block: {}", block_number);
-    Ok(())
-}
-
-// Alloy (NEW)
-use alloy::{
-    providers::{Provider, ProviderBuilder},
-    primitives::Address,
-};
-
-#[tokio::main]
-async fn main() -> eyre::Result<()> {
-    let provider = ProviderBuilder::new()
-        .connect_http("https://eth.llamarpc.com".parse()?);
+# Using Alloy documentation with coding agents
 
-    let block_number = provider.get_block_number().await?;
-    println!("Latest block: {}", block_number);
-    Ok(())
-}
-```
+Alloy publishes machine-readable documentation for coding agents. Give an agent the smallest relevant context instead of copying the entire manual into every prompt.
 
-#### Contract Interaction
-```rust
-// ethers-rs (OLD)
-use ethers::{
-    contract::{abigen, Contract},
-    providers::{Provider, Http},
-    types::{Address, U256},
-};
+## Recommended retrieval order
 
-abigen!(IERC20, "path/to/erc20.json");
+1. Start with [`llms.txt`](https://alloy.rs/llms.txt) to discover the canonical page for the task.
+2. Load the relevant guide and any pages it links to.
+3. Find the closest runnable example in the [Alloy examples repository](https://github.com/alloy-rs/examples).
+4. Use [docs.rs](https://docs.rs/alloy/latest/alloy/) for exact types, traits, methods, and feature gates.
+5. Use [`llms-full.txt`](https://alloy.rs/llms-full.txt) only when the agent cannot retrieve pages individually.
 
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let provider = Provider::<Http>::try_from("https://eth.llamarpc.com")?;
-    let contract_address = address!("A0b86a33E6441d1b3C0D2c9b1e3b6eE4c4d5e5e1");
-    let contract = IERC20::new(contract_address, provider.into());
+The Alloy version displayed in this site's navigation is the version targeted by hand-written documentation. Generated example pages identify the exact examples commit they were copied from.
 
-    let total_supply: U256 = contract.total_supply().call().await?;
-    println!("Total supply: {}", total_supply);
-    Ok(())
-}
+## Starter prompt
 
-// Alloy (NEW)
-use alloy::{
-    providers::{Provider, ProviderBuilder},
-    primitives::{Address, U256},
-    sol,
-};
+Use this as a short foundation, then append the task, target chain, transport, signer, and runtime constraints.
 
-sol! {
-    #[allow(missing_docs)]
-    #[sol(rpc)]
-    contract IERC20 {
-        function totalSupply() external view returns (uint256);
-    }
-}
+```text
+You are implementing a Rust application with Alloy.
 
-#[tokio::main]
-async fn main() -> eyre::Result<()> {
-    let provider = ProviderBuilder::new()
-        .connect_http("https://eth.llamarpc.com".parse()?);
+Use the supplied alloy.rs documentation and linked docs.rs API pages as the
+source of truth. Prefer the current stable Alloy APIs shown by those sources.
 
-    let contract_address = address!("A0b86a33E6441d1b3C0D2c9b1e3b6eE4c4d5e5e1");
-    let contract = IERC20::new(contract_address, provider);
+Requirements:
+- Name every required crate and feature flag.
+- Produce complete, runnable Rust rather than disconnected fragments.
+- Import the traits needed for extension methods.
+- Use ProviderBuilder for provider construction and sol! for typed contract APIs.
+- Distinguish consensus types, RPC types, and network-specific types.
+- Explain external prerequisites such as RPC_URL, WebSocket support, credentials,
+  hardware devices, Anvil, or a particular RPC namespace.
+- Read secrets and RPC URLs from environment variables; do not embed credentials
+  or depend on an undocumented shared endpoint.
+- Handle transport errors, JSON-RPC errors, contract reverts, transaction timeouts,
+  and confirmations when they are relevant to the task.
+- Do not invent methods or feature names. Verify exact symbols against docs.rs.
+- End with the commands needed to format and compile the result.
 
-    let total_supply = contract.totalSupply().call().await?;
-    println!("Total supply: {}", total_supply._0);
-    Ok(())
-}
+Task:
+<describe the desired program and constraints>
 ```
 
-#### Transaction Sending
-```rust
-// ethers-rs (OLD)
-use ethers::{
-    providers::{Provider, Http, Middleware},
-    signers::{LocalWallet, Signer},
-    middleware::SignerMiddleware,
-    types::{TransactionRequest, U256},
-};
+## Context that improves results
 
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let provider = Provider::<Http>::try_from("https://eth.llamarpc.com")?;
-    let wallet: LocalWallet = "your-private-key".parse()?;
-    let client = SignerMiddleware::new(provider, wallet);
+Include these details when they matter:
 
-    let tx = TransactionRequest::new()
-        .to("0xrecipient".parse::<Address>()?)
-        .value(U256::from(1000000000000000000u64)); // 1 ETH
+- Ethereum or another `Network` implementation.
+- HTTP, WebSocket, IPC, or a custom transport.
+- Read-only access or transaction signing.
+- Local key, mnemonic, keystore, hardware wallet, or cloud signer.
+- Required RPC namespaces such as Debug, Trace, Engine, TxPool, or Anvil.
+- Expected confirmation policy and reorg behavior.
+- Native, WASM, or `no_std` target.
+- Whether a local Anvil instance may be used for tests.
 
-    let tx_hash = client.send_transaction(tx, None).await?.await?;
-    println!("Transaction sent: {:?}", tx_hash);
-    Ok(())
-}
+## Verify generated projects
 
-// Alloy (NEW)
-use alloy::{
-    providers::{Provider, ProviderBuilder},
-    signers::local::PrivateKeySigner,
-    rpc::types::TransactionRequest,
-    primitives::{Address, U256},
-    network::TransactionBuilder,
-};
+Agents should validate their output with the compiler rather than treating plausible-looking code as complete.
 
-#[tokio::main]
-async fn main() -> eyre::Result<()> {
-    let signer: PrivateKeySigner = "your-private-key".parse()?;
-    let provider = ProviderBuilder::new()
-        .wallet(signer)
-        .connect_http("https://eth.llamarpc.com".parse()?);
-
-    let tx = TransactionRequest::default()
-        .with_to(address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045"))
-        .with_value(U256::from(1000000000000000000u64)); // 1 ETH
-
-    let tx_hash = provider.send_transaction(tx).await?.watch().await?;
-    println!("Transaction sent: {:?}", tx_hash);
-    Ok(())
-}
+```sh
+cargo fmt --check
+cargo check --all-targets --all-features
+cargo clippy --all-targets --all-features -- -D warnings
 ```
 
-### Migration Checklist
-
-1. **Update Dependencies**
-   ```toml
-   # Remove
-   # ethers = "2.0"
-
-   # Add
-   alloy = { version = "1.0", features = ["full"] }
-   eyre = "0.6"  # Better error handling
-   ```
-
-2. **Update Imports**
-   - Replace `ethers::types::*` with `alloy::primitives::*` for basic types
-   - Replace `ethers::providers::*` with `alloy::providers::*`
-   - Replace `ethers::signers::*` with `alloy::signers::*`
-   - Replace `ethers::contract::*` with `alloy::contract::*`
-
-3. **Update Type Names**
-   - `H160`, `H256`, etc. → `B160`, `B256`, etc.
-   - `BlockNumber` → `BlockNumberOrTag`
-   - Update address and hash type usage
-
-4. **Update Provider Pattern**
-   - Replace middleware stack with `ProviderBuilder` and fillers
-   - Use `with_recommended_fillers()` for common functionality
-   - Add wallet to provider with `.wallet(signer)`
-
-5. **Update Contract Bindings**
-   - Replace `abigen!` with `sol!` macro
-   - Add `#[sol(rpc)]` attribute for contract generation
-   - Update contract instantiation pattern
-
-6. **Update Error Handling**
-   - Consider using `eyre` for better error ergonomics
-   - Update error handling patterns for new API
-
-### Performance Benefits After Migration
-
-- **60% faster** U256 operations
-- **10x faster** ABI encoding/decoding with `sol!` macro
-- **Better type safety** with compile-time contract bindings
-- **Improved async patterns** with modern Rust async/await
-- **Modular architecture** with fillers and layers for customization
-
-</migrate_from_ethers>
-````
+For a minimal-feature project, also check the exact feature set used in production instead of relying only on `--all-features`.
diff --git a/vocs/docs/snippets/installation/alloy.toml b/vocs/docs/snippets/installation/alloy.toml
new file mode 100644
index 00000000..85c29c91
--- /dev/null
+++ b/vocs/docs/snippets/installation/alloy.toml
@@ -0,0 +1 @@
+alloy = "2.1.1"
diff --git a/vocs/docs/snippets/installation/individual-crates.toml b/vocs/docs/snippets/installation/individual-crates.toml
new file mode 100644
index 00000000..741b716b
--- /dev/null
+++ b/vocs/docs/snippets/installation/individual-crates.toml
@@ -0,0 +1,4 @@
+[dependencies]
+alloy-primitives = { version = "1.6.0", default-features = false, features = ["rand", "serde", "map-foldhash"] }
+alloy-provider = { version = "2.1.1", default-features = false, features = ["ipc"] }
+# ..snip..
diff --git a/vocs/docs/pages/templates/advanced/README.mdx b/vocs/docs/templates/advanced/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/advanced/README.mdx
rename to vocs/docs/templates/advanced/README.mdx
diff --git a/vocs/docs/pages/templates/big-numbers/README.mdx b/vocs/docs/templates/big-numbers/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/big-numbers/README.mdx
rename to vocs/docs/templates/big-numbers/README.mdx
diff --git a/vocs/docs/pages/templates/comparison/README.mdx b/vocs/docs/templates/comparison/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/comparison/README.mdx
rename to vocs/docs/templates/comparison/README.mdx
diff --git a/vocs/docs/pages/templates/contracts/README.mdx b/vocs/docs/templates/contracts/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/contracts/README.mdx
rename to vocs/docs/templates/contracts/README.mdx
diff --git a/vocs/docs/pages/templates/ens/README.mdx b/vocs/docs/templates/ens/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/ens/README.mdx
rename to vocs/docs/templates/ens/README.mdx
diff --git a/vocs/docs/pages/templates/fillers/README.mdx b/vocs/docs/templates/fillers/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/fillers/README.mdx
rename to vocs/docs/templates/fillers/README.mdx
diff --git a/vocs/docs/pages/templates/layers/README.mdx b/vocs/docs/templates/layers/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/layers/README.mdx
rename to vocs/docs/templates/layers/README.mdx
diff --git a/vocs/docs/pages/templates/node-bindings/README.mdx b/vocs/docs/templates/node-bindings/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/node-bindings/README.mdx
rename to vocs/docs/templates/node-bindings/README.mdx
diff --git a/vocs/docs/pages/templates/primitives/README.mdx b/vocs/docs/templates/primitives/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/primitives/README.mdx
rename to vocs/docs/templates/primitives/README.mdx
diff --git a/vocs/docs/pages/templates/providers/README.mdx b/vocs/docs/templates/providers/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/providers/README.mdx
rename to vocs/docs/templates/providers/README.mdx
diff --git a/vocs/docs/pages/templates/queries/README.mdx b/vocs/docs/templates/queries/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/queries/README.mdx
rename to vocs/docs/templates/queries/README.mdx
diff --git a/vocs/docs/pages/templates/sol-macro/README.mdx b/vocs/docs/templates/sol-macro/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/sol-macro/README.mdx
rename to vocs/docs/templates/sol-macro/README.mdx
diff --git a/vocs/docs/pages/templates/subscriptions/README.mdx b/vocs/docs/templates/subscriptions/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/subscriptions/README.mdx
rename to vocs/docs/templates/subscriptions/README.mdx
diff --git a/vocs/docs/pages/templates/transactions/README.mdx b/vocs/docs/templates/transactions/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/transactions/README.mdx
rename to vocs/docs/templates/transactions/README.mdx
diff --git a/vocs/docs/pages/templates/wallets/README.mdx b/vocs/docs/templates/wallets/README.mdx
similarity index 100%
rename from vocs/docs/pages/templates/wallets/README.mdx
rename to vocs/docs/templates/wallets/README.mdx
diff --git a/vocs/public/robots.txt b/vocs/public/robots.txt
new file mode 100644
index 00000000..7ad21166
--- /dev/null
+++ b/vocs/public/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://alloy.rs/sitemap.xml
diff --git a/vocs/versions.ts b/vocs/versions.ts
new file mode 100644
index 00000000..42ef5a85
--- /dev/null
+++ b/vocs/versions.ts
@@ -0,0 +1,5 @@
+/** Versions shown in hand-written documentation and generated dependency snippets. */
+export const versions = {
+  alloy: '2.1.1',
+  alloyCore: '1.6.0',
+} as const
diff --git a/vocs/vocs.config.ts b/vocs/vocs.config.ts
index 85b0695d..df6464d4 100644
--- a/vocs/vocs.config.ts
+++ b/vocs/vocs.config.ts
@@ -1,16 +1,19 @@
 import { defineConfig } from 'vocs/config'
 import { sidebar } from './sidebar'
+import { versions } from './versions'
+
 export default defineConfig({
-  title: 'alloy',
+  title: 'Alloy',
+  description: 'Alloy is a high-performance Rust toolkit for Ethereum and EVM-compatible chains.',
+  baseUrl: 'https://alloy.rs',
   logoUrl: '/alloy-logo.png',
   renderStrategy: 'full-static',
   srcDir: 'docs',
   sidebar,
   iconUrl: { light: '/favicon.png', dark: '/favicon.png' },
-  ogImageUrl: 'https://raw.githubusercontent.com/alloy-rs/book/master/vocs/docs/publics/banner.jpg',
+  ogImageUrl: 'https://alloy.rs/banner.jpg',
   socials: [
     { icon: 'github', link: "https://github.com/alloy-rs/alloy" },
-    { icon: 'telegram', link: "https://t.me/ethers_rs" },
   ],
   topNav: [
     { 
@@ -26,7 +29,7 @@ export default defineConfig({
       link: 'https://docs.rs/alloy/latest/alloy/',
     },
     { 
-      text: '2.0.5',
+      text: versions.alloy,
       items: [ 
         { 
           text: 'Changelog', 

From bc7f3aa805a727fa1c9393ac6c711ae636b6d9bb Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Thu, 16 Jul 2026 12:56:53 +0200
Subject: [PATCH 2/2] fix(docs): remove brittle endpoint defaults

---
 .../pages/contract-interactions/read-contract.mdx     |  3 ++-
 .../pages/contract-interactions/write-contract.mdx    |  3 ++-
 vocs/docs/pages/guides/speed-up-using-u256.md         |  3 ++-
 .../docs/pages/guides/static-dynamic-abi-in-alloy.mdx |  8 +++++---
 vocs/docs/pages/index.mdx                             | 11 ++++++++---
 vocs/docs/pages/introduction/getting-started.md       |  5 +++--
 vocs/docs/pages/rpc-providers/http-provider.md        |  2 +-
 vocs/docs/pages/rpc-providers/introduction.md         | 10 ++++++----
 vocs/docs/pages/transactions/transaction-lifecycle.md |  4 ++--
 9 files changed, 31 insertions(+), 18 deletions(-)

diff --git a/vocs/docs/pages/contract-interactions/read-contract.mdx b/vocs/docs/pages/contract-interactions/read-contract.mdx
index fdc09a6b..7698bad9 100644
--- a/vocs/docs/pages/contract-interactions/read-contract.mdx
+++ b/vocs/docs/pages/contract-interactions/read-contract.mdx
@@ -25,7 +25,8 @@ sol! { // [!code focus]
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
     // Initialize the provider.
-    let provider = ProviderBuilder::new().connect("https://ethereum.reth.rs/rpc").await?;
+    let rpc_url = std::env::var("RPC_URL")?;
+    let provider = ProviderBuilder::new().connect(&rpc_url).await?;
 
     // Instantiate the contract instance.
     let weth = address!("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2");
diff --git a/vocs/docs/pages/contract-interactions/write-contract.mdx b/vocs/docs/pages/contract-interactions/write-contract.mdx
index 7af18def..99b7c25d 100644
--- a/vocs/docs/pages/contract-interactions/write-contract.mdx
+++ b/vocs/docs/pages/contract-interactions/write-contract.mdx
@@ -35,13 +35,14 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Initialize a signer with a private key.
     let signer: PrivateKeySigner =
         "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80".parse()?;
+    let rpc_url = std::env::var("RPC_URL")?;
 
     // Instantiate a provider with the signer.
     let provider = ProviderBuilder::new() // [!code focus]
         // Signs transactions before dispatching them.
         .wallet(signer) // Signs the transactions // [!code focus]
         // Forking mainnet using anvil to avoid spending real ETH.
-        .connect_anvil_with_config(|a| a.fork("https://ethereum.reth.rs/rpc"));
+        .connect_anvil_with_config(|anvil| anvil.fork(rpc_url));
 
     // Setup WETH contract instance.
     let weth = address!("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2");
diff --git a/vocs/docs/pages/guides/speed-up-using-u256.md b/vocs/docs/pages/guides/speed-up-using-u256.md
index 2b3c72b7..144f7000 100644
--- a/vocs/docs/pages/guides/speed-up-using-u256.md
+++ b/vocs/docs/pages/guides/speed-up-using-u256.md
@@ -264,8 +264,9 @@ async fn main() -> Result<()> {
     let sushi_pair = get_sushi_pair();
 
     let wallet_address = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
+    let rpc_url = std::env::var("RPC_URL")?;
     let provider = ProviderBuilder::new()
-        .connect_anvil_with_wallet_and_config(|a| a.fork("https://ethereum.reth.rs/rpc"))?;
+        .connect_anvil_with_wallet_and_config(|anvil| anvil.fork(rpc_url))?;
 
     let executor = FlashBotsMultiCall::deploy(provider.clone(), wallet_address).await?;
     let iweth = IERC20::new(WETH_ADDR, provider.clone());
diff --git a/vocs/docs/pages/guides/static-dynamic-abi-in-alloy.mdx b/vocs/docs/pages/guides/static-dynamic-abi-in-alloy.mdx
index 6a113699..039b5032 100644
--- a/vocs/docs/pages/guides/static-dynamic-abi-in-alloy.mdx
+++ b/vocs/docs/pages/guides/static-dynamic-abi-in-alloy.mdx
@@ -143,9 +143,10 @@ sol!(
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
-    let provider = ProviderBuilder::new().connect("https://ethereum.reth.rs/rpc").await?;
+    let rpc_url = std::env::var("RPC_URL")?;
+    let provider = ProviderBuilder::new().connect(&rpc_url).await?;
     let iweth = IERC20::new(address!("C02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"), provider.clone());
-    let name = weth.name().call().await?;
+    let name = iweth.name().call().await?;
     println!("Name: {}", name); // => Wrapped Ether
 }
 ```
@@ -194,7 +195,8 @@ sol!(
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
-    let anvil = Anvil::new().fork("https://ethereum.reth.rs/rpc").try_spawn()?;
+    let rpc_url = std::env::var("RPC_URL")?;
+    let anvil = Anvil::new().fork(rpc_url).try_spawn()?;
     let wallet_address = anvil.addresses()[0];
     let provider = ProviderBuilder::new().connect(anvil.endpoint()).await?;
     let executor = FlashBotsMultiCall::deploy(provider.clone(), wallet_address).await?;
diff --git a/vocs/docs/pages/index.mdx b/vocs/docs/pages/index.mdx
index a723690e..f0d23692 100644
--- a/vocs/docs/pages/index.mdx
+++ b/vocs/docs/pages/index.mdx
@@ -80,6 +80,9 @@ import { HomePage } from "vocs";
 
 # Common Actions
 
+Networked snippets read `RPC_URL` (or `WS_URL` for WebSocket examples) from the environment. This
+keeps credentials out of source control and lets you choose the node provider.
+
 :::code-group
 
 ```rust showLineNumbers [read_contract.rs]
@@ -99,7 +102,8 @@ sol! { // [!code focus]
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
     // Initialize the provider.
-    let provider = ProviderBuilder::new().connect("https://ethereum.reth.rs/rpc").await?; // [!code focus]
+    let rpc_url = std::env::var("RPC_URL")?; // [!code focus]
+    let provider = ProviderBuilder::new().connect(&rpc_url).await?; // [!code focus]
 
     // Instantiate the contract instance.
     let weth = address!("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2");
@@ -139,13 +143,14 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Initialize a signer with a private key.
     let signer: PrivateKeySigner =
         "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80".parse()?;
+    let rpc_url = std::env::var("RPC_URL")?;
 
     // Instantiate a provider with the signer.
     let provider = ProviderBuilder::new() // [!code focus]
         // Signs transactions before dispatching them.
         .wallet(signer) // [!code focus]
         // Forking mainnet using anvil to avoid spending real ETH.
-        .connect_anvil_with_config(|a| a.fork("https://ethereum.reth.rs/rpc"));
+        .connect_anvil_with_config(|anvil| anvil.fork(rpc_url));
 
     // Setup WETH contract instance.
     let weth = address!("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2");
@@ -375,7 +380,7 @@ Alloy supports the following out of the box for a best-in-class developer experi
 
 Join the Community
 
-- Ask for support in the [Telegram chat](https://t.me/ethers_rs) or create an [issue on Github](https://github.com/alloy-rs/alloy/issues)
+- Report bugs or request features in the [Alloy issue tracker](https://github.com/alloy-rs/alloy/issues)
 - Join the 160+ developers by [contributing](https://github.com/alloy-rs/alloy/blob/main/CONTRIBUTING.md) to Alloy
 
 # Supporters
diff --git a/vocs/docs/pages/introduction/getting-started.md b/vocs/docs/pages/introduction/getting-started.md
index 1d8182c0..62621843 100644
--- a/vocs/docs/pages/introduction/getting-started.md
+++ b/vocs/docs/pages/introduction/getting-started.md
@@ -110,11 +110,12 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Initialize a random signer and get address from it
     let signer = PrivateKeySigner::random(); // [!code focus]
     let from_address = signer.address();
+    let rpc_url = std::env::var("RPC_URL")?;
 
     // Instantiate a provider with the signer
     let provider = ProviderBuilder::new() // [!code focus]
         .wallet(signer) // [!code focus]
-        .connect_anvil_with_config(|a| a.fork("https://ethereum.reth.rs/rpc"));
+        .connect_anvil_with_config(|anvil| anvil.fork(rpc_url));
 
     // Fund the random signer on the local Anvil fork
     provider // [!code focus]
@@ -186,7 +187,7 @@ sol! { // [!code focus]
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Connect to an Ethereum node via WebSocket
-    let ws = WsConnect::new("wss://reth-ethereum.ithaca.xyz/ws"); // [!code focus]
+    let ws = WsConnect::new(std::env::var("WS_URL")?); // [!code focus]
     let provider = ProviderBuilder::new().connect_ws(ws).await?; // [!code focus]
 
     // Uniswap V3 WETH-USDC Pool address
diff --git a/vocs/docs/pages/rpc-providers/http-provider.md b/vocs/docs/pages/rpc-providers/http-provider.md
index eed2f818..79e2f965 100644
--- a/vocs/docs/pages/rpc-providers/http-provider.md
+++ b/vocs/docs/pages/rpc-providers/http-provider.md
@@ -19,7 +19,7 @@ use std::error::Error;
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
     // Set up the HTTP transport which is consumed by the RPC client.
-    let rpc_url = "https://ethereum.reth.rs/rpc".parse()?;
+    let rpc_url = std::env::var("RPC_URL")?.parse()?;
 
     // Create a provider with the HTTP transport using the `reqwest` crate.
     let provider = ProviderBuilder::new().connect_http(rpc_url); // [!code focus]
diff --git a/vocs/docs/pages/rpc-providers/introduction.md b/vocs/docs/pages/rpc-providers/introduction.md
index c88490e1..e85184d2 100644
--- a/vocs/docs/pages/rpc-providers/introduction.md
+++ b/vocs/docs/pages/rpc-providers/introduction.md
@@ -14,18 +14,20 @@ Alloy provides concrete transport implementations for [`HTTP`](/rpc-providers/ht
 
 The [`connect`](https://docs.rs/alloy/latest/alloy/providers/struct.ProviderBuilder.html#method.connect) method on the [`ProviderBuilder`](https://docs.rs/alloy/latest/alloy/providers/struct.ProviderBuilder.html) will automatically determine the connection type (`Http`, `Ws` or `Ipc`) depending on the format of the URL.
 
+The examples use environment variables for endpoints so credentials are not committed to source
+control. Set `RPC_URL` to an HTTP endpoint or `WS_URL` to a WebSocket endpoint before running them.
+
 ```rust showLineNumbers
 //! Example of setting up a provider using the `.connect` method.
 
 use alloy::providers::{Provider, ProviderBuilder}; // [!code focus]
 use std::error::Error;
 
-const RPC_URL: &str = "https://ethereum.reth.rs/rpc";
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
-
-    // Instanties a provider using a string.
-    let provider = ProviderBuilder::new().connect(RPC_URL).await?; // [!code focus]
+    // Instantiate a provider using a caller-supplied endpoint.
+    let rpc_url = std::env::var("RPC_URL")?; // [!code focus]
+    let provider = ProviderBuilder::new().connect(&rpc_url).await?; // [!code focus]
 
     Ok(())
 }
diff --git a/vocs/docs/pages/transactions/transaction-lifecycle.md b/vocs/docs/pages/transactions/transaction-lifecycle.md
index 372ecb34..9e25a85e 100644
--- a/vocs/docs/pages/transactions/transaction-lifecycle.md
+++ b/vocs/docs/pages/transactions/transaction-lifecycle.md
@@ -37,8 +37,8 @@ let rpc_url = anvil.endpoint().parse()?;
 ```
 
 ```rust
-// Alternatively you can use any valid RPC URL found on https://chainlist.org/
-let rpc_url = "https://ethereum.reth.rs/rpc".parse()?;
+// Alternatively, use a caller-supplied endpoint.
+let rpc_url = std::env::var("RPC_URL")?.parse()?;
 ```
 
 Next let's define a `signer` for Alice. By default `Anvil` defines a mnemonic phrase: `"test test test test test test test test test test test junk"`. Make sure to not use this mnemonic phrase outside of testing environments. We add a signer to the `Provider` using the `.wallet` method which is responsible for signing the transactions.s