feat(docs): external-provider

docs/docs/guides/getting_started/introduction.md

@@ -61,7 +61,7 @@ Web3.js is a modular collection of packages, each of which serves a specific nee
 
 - [**Iban:**](/libdocs/Iban) The `web3-eth-iban` package allows you to switch between **Ethereum addresses and special banking-like addresses** (IBAN or BBAN) and simplifies conversion between the types.
 
-### Additional Supporting Packages 
+### Additional Supporting Packages
 
 - [**Web3 Core:**](/api/web3-core) subscriptions, request management, and configuration used by other Web3 packages
 
@@ -73,6 +73,8 @@ Web3.js is a modular collection of packages, each of which serves a specific nee
 
 - [**Web3 RPC Methods:**](/api/web3/namespace/rpcMethods) functions for making RPC requests to Ethereum using a given provider
 
+- [**Web3 RPC Providers:**](/api/web3-rpc-providers) utilities for working with well-known [remote providers](/guides/web3_providers_guide/#remote-provider)
+
 ### Plugins
 
 Web3.js supports [plugins](/guides/web3_plugin_guide/), which are another way to encapsulate capabilities that support a specific need. There are plugins that exist to support native features, like those described by [EIPs](https://eips.ethereum.org/) as well as plugins that are designed to support specific smart contracts, middleware, or even other Ethereum-compatible networks. Visit the [Web3.js plugins homepage](https://web3js.org/plugins) to view a list of the most important Web3.js plugins, which includes:

docs/docs/guides/getting_started/quickstart.md

@@ -43,25 +43,27 @@ import { Web3 } from 'web3';
 
 ## Initialize `Web3` with a Provider
 
-[Providers](/guides/web3_providers_guide/) are services that are responsible for enabling connectivity with the Ethereum network. The `Web3` object must be initialized with a valid provider to function as intended. Web3.js supports [HTTP](/guides/web3_providers_guide/#http-provider), [WebSocket](/guides/web3_providers_guide/#websocket-provider), and [IPC](/guides/web3_providers_guide/#ipc-provider) providers, and exposes packages for working with each type of provider.
+[Providers](/guides/web3_providers_guide/) are services that are responsible for enabling connectivity with the Ethereum network. Web3.js supports [HTTP](/guides/web3_providers_guide/#http-provider), [WebSocket](/guides/web3_providers_guide/#websocket-provider), and [IPC](/guides/web3_providers_guide/#ipc-provider) providers, and exposes packages for working with each type of provider.
+
+The default constructor for the `Web3` class uses preferred RPC partner [QuickNode](https://www.quicknode.com/) as an HTTP provider to connect to [Ethereum Mainnet](https://ethereum.org/en/developers/docs/networks/#ethereum-mainnet). The default provider is subject to usage limits and is only suitable for initial testing purposes. To support Web3.js development and remove usage limits, use the referral code `WEB3JS` to sign up for a QuickNode account and get 20% off for 2 months. Refer to the section on [Web3.js External Providers](/guides/web3_providers_guide/#web3js-external-providers) to learn how to configure the QuickNode provider to use an account token.
 
 Web3.js is in compliance with [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), the Ethereum Provider JavaScript API, so any EIP-1193 provider can be used to initialize the `Web3` object.
 
 ``` ts
 import { Web3 } from 'web3';
 
-// private RPC endpoint 
-const web3 = new Web3('https://mainnet.infura.io/v3/YOUR_INFURA_ID'); 
+// default QuickNode Ethereum Mainnet HTTP provider 
+const web3 = new Web3(); 
 
-// or public RPC endpoint
+// or specify a custom provider
 // const web3 = new Web3('https://eth.llamarpc.com'); 
 
-web3.eth.getBlockNumber().then(console.log);
-// ↳ 18849658n
+console.log(await web3.eth.getChainId());
+// ↳ 1n
 ```
 ## Querying the Blockchain
 
-After instantiating the `Web3` instance with a provider, the [`web3-eth`](/libdocs/Web3Eth) package can be used to fetch data from the Ethereum network:
+After instantiating the `Web3` instance, the [`web3-eth`](/libdocs/Web3Eth) package can be used to fetch data from the Ethereum network:
 
 ```ts
 // get the balance of an address

docs/docs/guides/web3_providers_guide/index.md

@@ -42,7 +42,7 @@ import { Web3, HttpProvider } from 'web3';
 
 // supply an HTTP provider as a URL string
 // highlight-next-line
-const web3 = new Web3('https://mainnet.infura.io/v3/YOUR_INFURA_ID');
+const web3 = new Web3('https://<PROVIDER_URL>');
 
 await web3.eth.getBlockNumber()
 // ↳ 18849658n
@@ -51,7 +51,7 @@ await web3.eth.getBlockNumber()
 
 // supply an HTTP provider by constructing a new HttpProvider
 // highlight-next-line
-const web3_2 = new Web3(new HttpProvider('https://mainnet.infura.io/v3/YOUR_INFURA_ID'));
+const web3_2 = new Web3(new HttpProvider('https://<PROVIDER_URL>'));
 
 await web3.eth.getBlockNumber()
 // ↳ 18849658n
@@ -84,7 +84,7 @@ const httpOptions = {
     } as RequestInit,
 };
 
-const web3 = new Web3(new HttpProvider('https://eth.llamarpc.com', httpOptions));
+const web3 = new Web3(new HttpProvider('https://<PROVIDER_URL>', httpOptions));
 ```
 
 ### WebSocket Provider
@@ -96,7 +96,7 @@ import { Web3, WebSocketProvider } from 'web3';
 
 // supply a WebSocket provider as a URL string
 // highlight-next-line
-const web3 = new Web3('wss://mainnet.infura.io/ws/v3/YOUR_INFURA_ID');
+const web3 = new Web3('wss://<PROVIDER_URL>');
 
 await web3.eth.getBlockNumber();	
 // ↳ 18849658n
@@ -105,7 +105,7 @@ await web3.eth.getBlockNumber();
 
 // supply a WebSocket provider by constructing a new WebSocketProvider
 // highlight-next-line
-const web3_2 = new Web3(new WebSocketProvider('wss://mainnet.infura.io/ws/v3/YOUR_INFURA_ID'));
+const web3_2 = new Web3(new WebSocketProvider('wss://<PROVIDER_URL>'));
 
 await web3.eth.getBlockNumber();
 // ↳ 18849658n
@@ -118,7 +118,7 @@ The [`WebSocketProvider` constructor](/api/web3-providers-ws/class/WebSocketProv
 ```ts title='Configuring a WebSocket Provider'
 // include both optional parameters
 const provider = new WebSocketProvider(
-  `ws://localhost:8545`,
+  `wss://<PROVIDER_URL>`,
   {
     headers: {
       // for node services that require an API key in a header
@@ -134,7 +134,7 @@ const provider = new WebSocketProvider(
 
 // OR include only ReconnectOptions
 const provider = new WebSocketProvider(
-  `ws://localhost:8545`,
+  `wss://<PROVIDER_URL>`,
   {},
   {
     delay: 500,
@@ -230,13 +230,15 @@ web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));
 
 ### Remote Provider
 
-Services like [Alchemy](https://www.alchemy.com/), [Infura](https://www.infura.io/), and [QuickNode](https://www.quicknode.com/) offer Ethereum node services that can be accessed via HTTP or Websocket.
+Services like [QuickNode](https://www.quicknode.com/), [Alchemy](https://www.alchemy.com/), and [Infura](https://www.infura.io/), offer Ethereum node services that can be accessed via HTTP or Websocket.
 
-```ts title='Alchemy, Infura, etc'
+```ts title='QuickNode, Alchemy, Infura, etc'
 import { Web3 } from 'web3';
-const web3 = new Web3('https://eth-mainnet.alchemyapi.io/v2/your-api-key');
+const web3 = new Web3('https://<REMOTE_PROVIDER_URL>');
 ```
 
+Web3.js provides helpful utilities for working with certain well-known remote providers. Read more about these utilities in the [Web3.js External Providers](#web3js-external-providers) section.
+
 ### Injected Provider
 
 Injected providers are supplied by an external third-party, most often a wallet or a web browser that is designed to be used with the Ethereum network. In addition to providing network connectivity, injected providers often supply one or more [accounts](/guides/wallet/). Web3.js supports any injected provider that is compliant with [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) and has been tested with multiple EIP-1193 providers, including [MetaMask](https://docs.metamask.io/wallet/reference/provider-api/), [Hardhat](https://hardhat.org/hardhat-runner/docs/advanced/hardhat-runtime-environment), and [Incubed (IN3)](https://in3.readthedocs.io/en/develop/index.html).
@@ -272,3 +274,56 @@ The following example should be run in a browser with the MetaMask extension ins
  });
 </script>
 ```
+
+## Web3.js External Providers
+
+The `web3-rpc-providers` package provides helpful utilities for working with certain well-known remote providers. The following example demonstrates using this package to create a WebSocket connection for the Ethereum [Sepolia](https://ethereum.org/en/developers/docs/networks/#sepolia) test network with [QuickNode](https://www.quicknode.com/):
+
+```js
+import { Web3 } from "web3";
+import { Network, QuickNodeProvider, Transport } from "web3-rpc-providers";
+
+const web3 = new Web3(new QuickNodeProvider(Network.ETH_SEPOLIA, Transport.WebSocket));
+console.log(await web3.eth.getChainId());
+// ↳ 11155111n
+```
+
+External providers can also be configured to use account tokens and custom hosts, as in the following example:
+
+```js
+import { Web3 } from "web3";
+import { QuickNodeProvider, Transport } from "web3-rpc-providers";
+
+const defaultSepoliaToken = "382a3b5a4b938f2d6e8686c19af4b22921fde2cd";
+const defaultSepoliaHost = "dimensional-fabled-glitter.ethereum-sepolia.quiknode.pro";
+const web3 = new Web3(
+  new QuickNodeProvider(
+    // omit network parameter
+    undefined,
+    Transport.WebSocket,
+    defaultSepoliaToken,
+    defaultSepoliaHost,
+  ),
+);
+
+console.log(await web3.eth.getChainId());
+// ↳ 11155111n
+```
+
+Constructors for external providers accept an optional argument for fine-tuning the configuration of the transport mechanism. See [Configuring HTTP Providers](#configuring-http-providers) and [Configuring WebSocket Providers](#configuring-websocket-providers) for more details. The following example demonstrates using this option to fine-tune the configuration for the default HTTP provider:
+
+```js
+import { Web3 } from "web3";
+import { QuickNodeProvider } from "web3-rpc-providers";
+
+const web3 = new Web3(
+  // use default arguments for network, transport, token, and host
+  new QuickNodeProvider(undefined, undefined, undefined, undefined, {
+    providerOptions: {
+      headers: {
+        "Content-Type": "application/json",
+      },
+    },
+  }),
+);
+```

docs/docusaurus.config.js

@@ -37,6 +37,7 @@ const packages = [
 	'web3-providers-http',
 	'web3-providers-ws',
 	'web3-providers-ipc',
+	'web3-rpc-providers',
 ];
 
 /** @type {import('@docusaurus/types').Config} */