From c859e91b2096f0fd80b65f40d848d78b4ff1f9cb Mon Sep 17 00:00:00 2001
From: Dan Forbes <dan.forbes@chainsafe.io>
Date: Tue, 3 Sep 2024 14:50:45 -0400
Subject: [PATCH] feat(docs): extend

Documentation for `Web3Context.extend` method

Closes #6768
---
 docs/docs/guides/advanced/custom_RPC.md   |  2 +-
 docs/docs/guides/advanced/extend.md       | 38 +++++++++++++++++++++++
 docs/docs/guides/advanced/tree_shaking.md |  2 +-
 3 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 docs/docs/guides/advanced/extend.md

diff --git a/docs/docs/guides/advanced/custom_RPC.md b/docs/docs/guides/advanced/custom_RPC.md
index 28ccfeeea63..6874062c814 100644
--- a/docs/docs/guides/advanced/custom_RPC.md
+++ b/docs/docs/guides/advanced/custom_RPC.md
@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 Web3.js is a popular library for interacting with the Ethereum blockchain. It provides a set of APIs to interact with Ethereum nodes via JSON-RPC calls. For adding new JSON-RPC function calls to the library, you can do so using the plugin feature in web3.js 4.x. This allows you to extend the functionality of Web3.js and add support for new JSON-RPC methods.
 
 :::caution
-In Web3.js 1.x, `web3.extend()` function could be used to add new JSON-RPC methods. `web3.extend()` is also available in Web3 v4.0.4+ with some breaking changes. However it is recommended to use Web3 Plugin feature for extending web3 functionality if you are developing new feature.
+In Web3.js 1.x, `web3.extend()` function could be used to add new JSON-RPC methods. `web3.extend()` is also available in Web3 v4.0.4+ with some breaking changes. However it is recommended to use Web3 Plugin feature for extending web3 functionality if you are developing new feature. Read the ["Extending Web3.js"](/guides/advanced/extend) guide to learn more about the legacy `web3.extend()` method.
 :::
 
 Following tutorial will guide you through the process of creating a custom plugin to extend the functionality of web3.js 4.x and add support for new RPC methods.
diff --git a/docs/docs/guides/advanced/extend.md b/docs/docs/guides/advanced/extend.md
new file mode 100644
index 00000000000..4b9d011db73
--- /dev/null
+++ b/docs/docs/guides/advanced/extend.md
@@ -0,0 +1,38 @@
+---
+sidebar_position: 2
+sidebar_label: Extending Web3.js
+---
+
+# Extending Web3.js
+
+Although the preferred way to add custom RPC methods to Web3.js is to [create a plugin](/guides/advanced/custom_RPC), Web3.js also exposes a [legacy `extend` method](/api/web3/class/Web3Context#extend) that can be used for the same purpose. Keep reading to learn how to use the legacy `extend` method to add a custom RPC method to an instance of Web3.js.
+
+## `ExtensionObject`
+
+The legacy `extend` method accepts a single parameter that should implement the [`ExtensionObject` interface](/api/web3/namespace/core/#ExtensionObject). An `ExtensionObject` consists of two properties: an optional `string` property named `property` and a required property named `methods` that is an array of objects that implement the [`Method` interface](/api/web3/namespace/core/#Method). The `Method` interface specifies two properties, both of which are required and both of which are strings: `name` and `call`. The `property` property of an `Extension` object can be used to specify the name of the Web3.js member property that will expose the custom RPC methods (if this parameter is omitted, the new RPC methods will be exposed by the "root" Web3.js object). Each element of the `methods` array from the `ExtensionObject` specifies a new custom RPC method - the `name` property is the name of the new function that will be used to call the custom RPC method and the `call` property is the actual RPC endpoint that should be invoked. The new function will accept parameters that will be passed along when invoking the RPC endpoint.
+
+Here is a complete example of using the legacy `extend` method:
+
+```js
+import { Web3 } from "web3";
+
+const web3 = new Web3("https://eth.llamarpc.com");
+
+async function main() {
+  web3.extend({
+    property: "BlockReceipts",
+    methods: [
+      {
+        name: "getBlockReceipts",
+        // https://www.quicknode.com/docs/ethereum/eth_getBlockReceipts
+        call: "eth_getBlockReceipts",
+      },
+    ],
+  });
+
+  const receipts = await web3.BlockReceipts.getBlockReceipts("latest");
+  console.log(receipts);
+}
+
+main();
+```
diff --git a/docs/docs/guides/advanced/tree_shaking.md b/docs/docs/guides/advanced/tree_shaking.md
index 46f301e738c..43b4aa8b717 100644
--- a/docs/docs/guides/advanced/tree_shaking.md
+++ b/docs/docs/guides/advanced/tree_shaking.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 sidebar_label: Tree Shaking Guide
 ---