alloy-rs · mattsse · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026
@@ -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

@@ -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,15 +96,20 @@ 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:
 
 ```sh
 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
 

@@ -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

@@ -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)
@@ -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,40 +64,40 @@ 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
 
 
       # 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
+main
@@ -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");

@@ -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");

@@ -1,3 +1,3 @@
-import Template from '../../templates/advanced/README.mdx'
+import Template from '../../../templates/advanced/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/big-numbers/README.mdx'
+import Template from '../../../templates/big-numbers/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/comparison/README.mdx'
+import Template from '../../../templates/comparison/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/contracts/README.mdx'
+import Template from '../../../templates/contracts/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/ens/README.mdx'
+import Template from '../../../templates/ens/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/fillers/README.mdx'
+import Template from '../../../templates/fillers/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/layers/README.mdx'
+import Template from '../../../templates/layers/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/node-bindings/README.mdx'
+import Template from '../../../templates/node-bindings/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/primitives/README.mdx'
+import Template from '../../../templates/primitives/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/providers/README.mdx'
+import Template from '../../../templates/providers/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/queries/README.mdx'
+import Template from '../../../templates/queries/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/sol-macro/README.mdx'
+import Template from '../../../templates/sol-macro/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/subscriptions/README.mdx'
+import Template from '../../../templates/subscriptions/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/transactions/README.mdx'
+import Template from '../../../templates/transactions/README.mdx'
 
 <Template />
@@ -1,3 +1,3 @@
-import Template from '../../templates/wallets/README.mdx'
+import Template from '../../../templates/wallets/README.mdx'
 
 <Template />
@@ -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());

@@ -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?;