From b76cd7f331ccf1666db54b8ea418890aaaa15600 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Thu, 30 May 2024 08:00:46 -0700 Subject: [PATCH] Formatting fixes for recently updated pages --- .../guides/getting_started/introduction.md | 4 +- .../docs/guides/getting_started/quickstart.md | 75 +++++++++--------- .../docs/guides/web3_providers_guide/index.md | 77 +++++++++---------- 3 files changed, 79 insertions(+), 77 deletions(-) diff --git a/docs/docs/guides/getting_started/introduction.md b/docs/docs/guides/getting_started/introduction.md index 0e92051b4ce..c32338d324d 100644 --- a/docs/docs/guides/getting_started/introduction.md +++ b/docs/docs/guides/getting_started/introduction.md @@ -49,7 +49,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 @@ -61,7 +61,7 @@ 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 -## Advantages over other libraries +## Advantages Over Other Libraries - **Extensive Documentation and Community**: Web3.js is one of the most established Ethereum libraries, which means it benefits from extensive documentation and a large, active community. Web3.js is widely adopted and has been thoroughly tested in various production environments, and is compatible with a broad range of other tools and services in the Ethereum ecosystem. diff --git a/docs/docs/guides/getting_started/quickstart.md b/docs/docs/guides/getting_started/quickstart.md index 886b2690e19..80551ad735b 100644 --- a/docs/docs/guides/getting_started/quickstart.md +++ b/docs/docs/guides/getting_started/quickstart.md @@ -7,7 +7,7 @@ sidebar_label: Quickstart Use the live code editor to try Web3.js in your browser now! Keep reading to learn how to use Web3.js in a local development environment. -## Live code editor +## Live Code Editor @@ -41,7 +41,7 @@ For ESM-style imports, use: import { Web3 } from 'web3'; ``` -## Initialize `Web3` with a provider +## 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. @@ -50,16 +50,16 @@ Web3.js is in compliance with [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193 ``` ts import { Web3 } from 'web3'; -//private RPC endpoint +// private RPC endpoint const web3 = new Web3('https://mainnet.infura.io/v3/YOUR_INFURA_ID'); -//or public RPC endpoint -//const web3 = new Web3('https://eth.llamarpc.com'); +// or public RPC endpoint +// const web3 = new Web3('https://eth.llamarpc.com'); web3.eth.getBlockNumber().then(console.log); // ↳ 18849658n ``` -## Querying the blockchain +## 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: @@ -85,18 +85,18 @@ await web3.eth.getGasPrice(); // ↳ 23879160756n ``` -## Setting up a wallet +## Setting Up a Wallet To send transactions to the Ethereum network (e.g. [transferring ETH](/guides/getting_started/quickstart#transfer-eth) or [interacting with smart contracts](/guides/getting_started/quickstart#interact-with-smart-contracts)), it's necessary to use an [account](https://ethereum.org/en/developers/docs/accounts/) with funds to cover [gas fees](https://ethereum.org/en/developers/docs/gas/). The [`Wallet`](/api/web3-eth-accounts/class/Wallet) object is designed to manage a set of accounts that can be used to send transactions with [`web3.eth.sendTransaction`](/api/web3/class/Web3Eth#sendTransaction) or [`web3.eth.contract.methods.contractfunction().send()`](/api/web3-eth-contract/class/Contract). -### Create a random account +### Create a Random Account Using the `Wallet` to create a random account is a good way to accelerate the development process, but it's not suitable for mainnet or production uses, since random accounts will not have funds to cover gas fees. Use the [`Wallet.create`](/api/web3-eth-accounts/class/Wallet#create) method to create a random account. ```ts -//create random wallet with 1 account +// create random wallet with 1 account web3.eth.accounts.wallet.create(1) /* ↳ Wallet(1) @@ -119,7 +119,7 @@ Wallet(1) */ ``` -### Add an account from a private key +### Add an Account from a Private Key Use the [`Wallet.add`](/api/web3-eth-accounts/class/Wallet#add) method to use a private key to add an existing account to a wallet. @@ -128,7 +128,7 @@ Private keys are sensitive data and should be treated as such. Make sure that pr ::: ```ts -//the private key must start with the '0x' prefix +// the private key must start with the "0x" prefix const account = web3.eth.accounts.wallet.add('0x50d349f5cf627d44858d6fcb6fbf15d27457d35c58ba2d5cfeaf455f25db5bec'); console.log(account[0].address); @@ -143,39 +143,39 @@ console.log(account[0].privateKey); This is an example of using a private key to add an account to a wallet, and then using that account to transfer ETH: ```ts -//add an account to a wallet +// add an account to a wallet const account = web3.eth.accounts.wallet.add('0x50d349f5cf627d44858d6fcb6fbf15d27457d35c58ba2d5cfeaf455f25db5bec'); -//create transaction object to send 1 eth to '0xa32...c94' address from the account[0] +// create transaction object to send 1 eth to '0xa32...c94' address from the account[0] const tx = { from: account[0].address, to: '0xa3286628134bad128faeef82f44e99aa64085c94', value: web3.utils.toWei('1', 'ether') }; -//the `from` address must match the one previously added with wallet.add +// the "from" address must match the one previously added with wallet.add -//send the transaction +// send the transaction const txReceipt = await web3.eth.sendTransaction(tx); console.log('Tx hash:', txReceipt.transactionHash) // ↳ Tx hash: 0x03c844b069646e08af1b6f31519a36e3e08452b198ef9f6ce0f0ccafd5e3ae0e ``` -## Interact with smart contracts +## Interact with Smart Contracts [Smart contracts](https://ethereum.org/en/developers/docs/smart-contracts/) are programs that run on the Ethereum network. Keep reading to learn how to use Web3.js to interact with smart contracts. -### Instantiate a contract +### Instantiate a Smart Contract The first step to interacting with a smart contract is to instantiate it, which requires the [ABI](https://docs.soliditylang.org/en/develop/abi-spec.html) and address of the smart contract. The following examples demonstrates instantiating the [Uniswap](https://uniswap.org/) token smart contract: ```ts -//Uniswap token smart contract address (mainnet) +// Uniswap token smart contract address (Mainnet) const address = '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984' -//you can find the complete ABI in etherscan.io -//https://etherscan.io/address/0x1f9840a85d5af5bf1d1762f925bdaddc4201f984#code +// you can find the complete ABI on etherscan.io +// https://etherscan.io/address/0x1f9840a85d5af5bf1d1762f925bdaddc4201f984#code const ABI = [ { @@ -190,60 +190,63 @@ const ABI = }, ]; -//instantiate the smart contract +// instantiate the smart contract const uniswapToken = new web3.eth.Contract(abi, address); ``` -### Read methods +### Read Methods Since reading data from a smart contract does not consume any gas, it's not necessary to use an account to do so. Here are some examples of reading data from the Uniswap token smart contract: ```ts -//make the call to the contract +// make the call to the contract const symbol = await uniswapToken.methods.symbol().call(); console.log('Uniswap symbol:',symbol); // ↳ Uniswap symbol: UNI -//make the call to the contract +// make the call to the contract const totalSupply = await uniswapToken.methods.totalSupply().call(); console.log('Uniswap Total supply:', totalSupply); // ↳ Uniswap Total Supply: 1000000000000000000000000000n ``` -### Write methods +### Write Methods Writing data to a smart contract consumes gas and requires the use of an account with funds. The following example demonstrates such an interaction: ```ts -//address to send the token +// address to send the token const to = '0xcf185f2F3Fe19D82bFdcee59E3330FD7ba5f27ce'; -//value to transfer (1 with 18 decimals) +// value to transfer (1 with 18 decimals) const value = web3.utils.toWei('1','ether'); -//send the transaction => return the Tx receipt +// send the transaction => return the Tx receipt const txReceipt = await uniswapToken.methods.transfer(to,value).send({from: account[0].address}); console.log('Tx hash:',txReceipt.transactionHash); // ↳ Tx hash: 0x14273c2b5781cc8f1687906c68bfc93482c603026d01b4fd37a04adb6217ad43 ``` -### Query past events +### Query Past Events Smart contracts emit [events](https://ethereum.org/en/developers/docs/smart-contracts/anatomy/#events-and-logs) to communicate important interactions. This example demonstrates how to query the Uniswap token smart contract for all `Transfer` events that occurred after a certain block number: ```ts -//get past `Transfer` events from block 18850576 +// get past `Transfer` events from block 18850576 const eventTransfer = await uniswapToken.getPastEvents('Transfer', { fromBlock: 18850576 }); console.log(eventTransfer); // ↳ [{...},{...}, ...] array with all the events emitted -//you can only query logs from the previous 100_000 blocks ``` -### Subscribing to events +:::note +You can only query logs from the most recent 100,000 blocks. +::: + +### Subscribing to Events Web3.js allows user to subscribe to events for real-time notification of important contract interactions. Here is an example of creating a subscription to the Uniswap token's `Transfer` event: @@ -254,16 +257,16 @@ HTTP providers do not support real-time event subscriptions. Use one of the othe ```ts import { Web3 } from 'web3'; -//WebSocket provider +// WebSocket provider const web3 = new Web3('wss://ethereum.publicnode.com'); -//instantiate contract +// instantiate contract const uniswapToken = new web3.eth.Contract(abi, address) -//create the subcription to all the 'Transfer' events +// create the subscription to all the 'Transfer' events const subscription = uniswapToken.events.Transfer(); -//listen to the events +// listen to the events subscription.on('data',console.log); // ↳ [{...},{...}, ...] live events will be printed in the console ``` diff --git a/docs/docs/guides/web3_providers_guide/index.md b/docs/docs/guides/web3_providers_guide/index.md index 1c1a0c334cb..726ccd8c229 100644 --- a/docs/docs/guides/web3_providers_guide/index.md +++ b/docs/docs/guides/web3_providers_guide/index.md @@ -3,7 +3,7 @@ sidebar_position: 1 sidebar_label: 'Mastering Providers' --- -# Web3js providers overview +# Web3.js Providers Overview Providers are services that are responsible for enabling Web3.js connectivity with the Ethereum network. Using a provider to connect your application to an Ethereum node is necessary for querying data, sending transactions, and interacting with smart contracts. This guide will explore the different types of Web3.js providers, how to set them up, and how to use them in an application. @@ -14,7 +14,7 @@ import { Web3 } from 'web3'; const web3 = new Web3(/* PROVIDER*/); -//calling any method that interact with the network would use the previous passed provider. +// calling any method that interacts with the network will use the supplied provider await web3.eth.getBlockNumber(); ``` @@ -40,8 +40,8 @@ HTTP is a request-response protocol and does not support persistent connection, ``` ts title='Initialize an HTTP Provider' import { Web3, HttpProvider } from 'web3'; -//supply an HTTP provider as a URL string -//highlight-next-line +// supply an HTTP provider as a URL string +// highlight-next-line const web3 = new Web3('https://mainnet.infura.io/v3/YOUR_INFURA_ID'); await web3.eth.getBlockNumber() @@ -49,8 +49,8 @@ await web3.eth.getBlockNumber() // OR -//supply an HTTP provider by constructing a new HttpProvider -//highlight-next-line +// 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')); await web3.eth.getBlockNumber() @@ -87,15 +87,15 @@ const httpOptions = { const web3 = new Web3(new HttpProvider('https://eth.llamarpc.com', httpOptions)); ``` -### WebSocket provider +### WebSocket Provider WebSockets support a persistent connection between a client and a server, which means they are suitable for use cases that require real-time [event subscriptions](/guides/events_subscriptions/). ``` ts title='Initialize WS Provider' import { Web3, WebSocketProvider } from 'web3'; -//supply a WebSocket provider as a URL string -//highlight-next-line +// supply a WebSocket provider as a URL string +// highlight-next-line const web3 = new Web3('wss://mainnet.infura.io/ws/v3/YOUR_INFURA_ID'); await web3.eth.getBlockNumber(); @@ -103,8 +103,8 @@ await web3.eth.getBlockNumber(); // OR -//supply a WebSocket provider by constructing a new WebSocketProvider -//highlight-next-line +// 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')); await web3.eth.getBlockNumber(); @@ -116,12 +116,12 @@ await web3.eth.getBlockNumber(); The [`WebSocketProvider` constructor](/api/web3-providers-ws/class/WebSocketProvider#constructor) accepts two optional parameters that can be used to configure the behavior of the `WebSocketProvider`: the first parameter must be of type [`ClientRequestArgs`](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_http_d_._http_.clientrequestargs.html) or of [`ClientOptions`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/e5ee5eae6a592198e469ad9f412bab8d223fcbb6/types/ws/index.d.ts#L243) and the second parameter must be of type [`ReconnectOptions`](/api/web3/namespace/utils#ReconnectOptions). ```ts title='Configuring a WebSocket Provider' -//include both optional parameters +// include both optional parameters const provider = new WebSocketProvider( `ws://localhost:8545`, { headers: { - //for node services that require an API key in a header + // for node services that require an API key in a header 'x-api-key': '', }, }, @@ -132,7 +132,7 @@ const provider = new WebSocketProvider( } ); -//OR include only ReconnectOptions +// OR include only ReconnectOptions const provider = new WebSocketProvider( `ws://localhost:8545`, {}, @@ -150,10 +150,10 @@ IPC (inter-process communication) providers offer high-performance local communi ``` ts title='Initialize IPC Provider' import { Web3 } from 'web3'; -//highlight-next-line +// highlight-next-line import { IpcProvider } from 'web3-providers-ipc'; -//highlight-next-line +// highlight-next-line const web3 = new Web3(new IpcProvider('/users/myuser/.ethereum/geth.ipc')); await web3.eth.getBlockNumber(); @@ -167,7 +167,7 @@ The [`IpcProvider` constructor](/api/web3-providers-ipc/class/IpcProvider#constr ```ts title='Configuring an IPC Provider' -//include both optional parameters +// include both optional parameters const provider = new IpcProvider( '/Users/myuser/Library/Ethereum/geth.ipc', { @@ -180,7 +180,7 @@ const provider = new IpcProvider( } ); -//OR include only ReconnectOptions +// OR include only ReconnectOptions const provider = new IpcProvider( '/Users/myuser/Library/Ethereum/geth.ipc', {}, @@ -208,22 +208,23 @@ Local providers can usually be accessed via IPC, HTTP, or WebSocket. The followi import { Web3 } from 'web3'; import { IpcProvider } from 'web3-providers-ipc'; -//highlight-next-line -//IPC provider -const web3 = new Web3(new IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc'));//mac os path -// on windows the path is: '\\\\.\\pipe\\geth.ipc' -// on linux the path is: '/users/myuser/.ethereum/geth.ipc' +// highlight-next-line +// IPC provider +const web3 = new Web3(new IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc')); +// the path above is for macOS +// on Windows the path is: '\\\\.\\pipe\\geth.ipc' +// on Linux the path is: '/users/myuser/.ethereum/geth.ipc' -//highlight-next-line -//HTTP provider +// highlight-next-line +// HTTP provider web3.setProvider('http://localhost:8545'); -// or +// OR web3.setProvider(new Web3.providers.HttpProvider('http://localhost:8545')); -//highlight-next-line -//WebSocket provider +// highlight-next-line +// WebSocket provider web3.setProvider('ws://localhost:8546'); -// or +// OR web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546')); ``` @@ -232,8 +233,6 @@ web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546')); 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. ```ts title='Alchemy, Infura, etc' -// like Alchemy (https://www.alchemyapi.io/supernode) -// or infura (https://mainnet.infura.io/v3/your_infura_key) import { Web3 } from 'web3'; const web3 = new Web3('https://eth-mainnet.alchemyapi.io/v2/your-api-key'); ``` @@ -250,24 +249,24 @@ The following example should be run in a browser with the MetaMask extension ins