From 6f7d4c68ca77def5b09933ac28761878be7ec946 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Fri, 21 Jun 2024 08:45:28 -0700 Subject: [PATCH 1/8] Add Documentation for External Providers Closes #7115 --- .../docs/guides/getting_started/quickstart.md | 16 ++++---- .../docs/guides/web3_providers_guide/index.md | 37 +++++++++++++++++++ 2 files changed, 46 insertions(+), 7 deletions(-) diff --git a/docs/docs/guides/getting_started/quickstart.md b/docs/docs/guides/getting_started/quickstart.md index 80551ad735b..c18310e2194 100644 --- a/docs/docs/guides/getting_started/quickstart.md +++ b/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 an HTTP provider from [QuickNode](https://www.quicknode.com/) to connect to [Ethereum Mainnet](https://ethereum.org/en/enterprise/). The default provider is subject to usage limits and is only suitable for initial testing purposes. To remove usage limits and support continued Web3.js development, use this referral link to sign up for a QuickNode account. 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. 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 diff --git a/docs/docs/guides/web3_providers_guide/index.md b/docs/docs/guides/web3_providers_guide/index.md index 726ccd8c229..1c51a632665 100644 --- a/docs/docs/guides/web3_providers_guide/index.md +++ b/docs/docs/guides/web3_providers_guide/index.md @@ -237,6 +237,8 @@ import { Web3 } from 'web3'; const web3 = new Web3('https://eth-mainnet.alchemyapi.io/v2/your-api-key'); ``` +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,38 @@ The following example should be run in a browser with the MetaMask extension ins }); ``` + +## 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 test network with QuickNode: + +```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 API 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 +``` From 1321f29e074285a2105af03dd3e349527ba86d33 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Fri, 21 Jun 2024 09:05:15 -0700 Subject: [PATCH 2/8] Update Links & Verbiage --- docs/docs/guides/getting_started/quickstart.md | 2 +- docs/docs/guides/web3_providers_guide/index.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/guides/getting_started/quickstart.md b/docs/docs/guides/getting_started/quickstart.md index c18310e2194..12ad82e90b9 100644 --- a/docs/docs/guides/getting_started/quickstart.md +++ b/docs/docs/guides/getting_started/quickstart.md @@ -45,7 +45,7 @@ import { Web3 } from 'web3'; [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 an HTTP provider from [QuickNode](https://www.quicknode.com/) to connect to [Ethereum Mainnet](https://ethereum.org/en/enterprise/). The default provider is subject to usage limits and is only suitable for initial testing purposes. To remove usage limits and support continued Web3.js development, use this referral link to sign up for a QuickNode account. 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. +The default constructor for the `Web3` class uses an HTTP provider from [QuickNode](https://www.quicknode.com/) 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 remove usage limits and support continued Web3.js development, use this referral link to sign up for a QuickNode account. 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. diff --git a/docs/docs/guides/web3_providers_guide/index.md b/docs/docs/guides/web3_providers_guide/index.md index 1c51a632665..497c9cb06d4 100644 --- a/docs/docs/guides/web3_providers_guide/index.md +++ b/docs/docs/guides/web3_providers_guide/index.md @@ -277,7 +277,7 @@ The following example should be run in a browser with the MetaMask extension ins ## 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 test network with QuickNode: +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"; @@ -288,7 +288,7 @@ console.log(await web3.eth.getChainId()); // ↳ 11155111n ``` -External providers can also be configured to use API tokens and custom hosts, as in the following example: +External providers can also be configured to use account tokens and custom hosts, as in the following example: ```js import { Web3 } from "web3"; From 5c706102e997e747477983d31565d9df5f3e902d Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Fri, 21 Jun 2024 10:07:01 -0700 Subject: [PATCH 3/8] Redwan Suggestions --- docs/docs/guides/getting_started/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guides/getting_started/quickstart.md b/docs/docs/guides/getting_started/quickstart.md index 12ad82e90b9..c0e4c33cb43 100644 --- a/docs/docs/guides/getting_started/quickstart.md +++ b/docs/docs/guides/getting_started/quickstart.md @@ -45,7 +45,7 @@ import { Web3 } from 'web3'; [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 an HTTP provider from [QuickNode](https://www.quicknode.com/) 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 remove usage limits and support continued Web3.js development, use this referral link to sign up for a QuickNode account. 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. +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 this referral link to sign up for a QuickNode account. 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. From d08c73846e8f4e8eeacef788501c6da3a27d82c7 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Mon, 12 Aug 2024 16:46:19 -0400 Subject: [PATCH 4/8] Update with referral code --- docs/docs/guides/getting_started/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guides/getting_started/quickstart.md b/docs/docs/guides/getting_started/quickstart.md index c0e4c33cb43..6ed9bf09045 100644 --- a/docs/docs/guides/getting_started/quickstart.md +++ b/docs/docs/guides/getting_started/quickstart.md @@ -45,7 +45,7 @@ import { Web3 } from 'web3'; [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 this referral link to sign up for a QuickNode account. 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. +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. From 6d47f5e0011de40ea3e63f0841119eb31affd5e4 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Tue, 13 Aug 2024 13:49:49 -0400 Subject: [PATCH 5/8] Update API Docs & Add Providers to Supporting Packages --- docs/docs/guides/getting_started/introduction.md | 4 +++- docs/docusaurus.config.js | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/docs/guides/getting_started/introduction.md b/docs/docs/guides/getting_started/introduction.md index 303401639f9..137c997bb4e 100644 --- a/docs/docs/guides/getting_started/introduction.md +++ b/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: diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 2fff620f657..c6c5b94c4a1 100644 --- a/docs/docusaurus.config.js +++ b/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} */ From 181a86d5b06f47b18301c7085c851efb89966a04 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Wed, 14 Aug 2024 09:49:35 -0400 Subject: [PATCH 6/8] Remove References to Specific Providers --- .../docs/guides/web3_providers_guide/index.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/docs/guides/web3_providers_guide/index.md b/docs/docs/guides/web3_providers_guide/index.md index 497c9cb06d4..1079af918c0 100644 --- a/docs/docs/guides/web3_providers_guide/index.md +++ b/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://'); 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://')); 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://', 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://'); 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://')); 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://`, { 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://`, {}, { delay: 500, @@ -230,11 +230,11 @@ 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://'); ``` 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. From a75d72b10132c7d30c281106b15c4b831c68fb84 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Wed, 21 Aug 2024 10:11:45 -0400 Subject: [PATCH 7/8] Document Transport Configuration --- docs/docs/guides/web3_providers_guide/index.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/docs/guides/web3_providers_guide/index.md b/docs/docs/guides/web3_providers_guide/index.md index 1079af918c0..53d3dc206f6 100644 --- a/docs/docs/guides/web3_providers_guide/index.md +++ b/docs/docs/guides/web3_providers_guide/index.md @@ -309,3 +309,21 @@ const web3 = new Web3( console.log(await web3.eth.getChainId()); // ↳ 11155111n ``` + +Constructors for external providers accept an optional argument for fine-tuning the configuring 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", + }, + }, + }), +); +``` From c24010d6952a06abcf01580d7f58d24caecc0155 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Wed, 21 Aug 2024 10:16:23 -0400 Subject: [PATCH 8/8] Fix Small Typo --- docs/docs/guides/web3_providers_guide/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guides/web3_providers_guide/index.md b/docs/docs/guides/web3_providers_guide/index.md index 53d3dc206f6..120227a5745 100644 --- a/docs/docs/guides/web3_providers_guide/index.md +++ b/docs/docs/guides/web3_providers_guide/index.md @@ -310,7 +310,7 @@ console.log(await web3.eth.getChainId()); // ↳ 11155111n ``` -Constructors for external providers accept an optional argument for fine-tuning the configuring 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: +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";