diff --git a/docs/docs/guides/getting_started/quickstart.md b/docs/docs/guides/getting_started/quickstart.md index d023e01bb9f..c1db2a9fdc8 100644 --- a/docs/docs/guides/getting_started/quickstart.md +++ b/docs/docs/guides/getting_started/quickstart.md @@ -5,6 +5,7 @@ sidebar_label: Quickstart # 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 @@ -12,29 +13,29 @@ sidebar_label: Quickstart ## Installation -If NPM is being used as package manager, use the following for installing the web3.js library. +If NPM is being used as package manager, install Web3.js with the following command: ``` npm i web3 ``` -For installing using yarn package manager: +For projects using Yarn as a package manager, use: ``` yarn add web3 ``` -Note: Installing web3.js in this way will bring in all web3.js sub-packages, if you only need specific packages, it is recommended to install the specific required packages (e.g, if you want the contract package `npm i web3-eth-contract` instead) +Note: Installing Web3.js in this way will bring in all Web3.js sub-[packages](/#packages). If you only need specific packages, it is recommended to install them individually (e.g, if you want the [Contract](/libdocs/Contract) package, use `npm i web3-eth-contract` instead) ## Importing Web3.js -Web3.js v4 supports both CJS ( CommonJS ) and native ESM module imports. For importing the main Web3 class in CJS you can use: +Web3.js v4 supports both CommonJS (CJS) and native ECMAScript module (ESM) imports. For importing the main Web3 class in CJS, use: ``` js const { Web3 } = require('web3'); ``` -and for ESM style imports, you can use: +For ESM-style imports, use: ``` ts import { Web3 } from 'web3'; @@ -42,11 +43,9 @@ import { Web3 } from 'web3'; ## Initialize `Web3` with a provider -Web3.js is in compliance with [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) so any EIP-1193 provider can be injected in web3.js . There are HTTP, WebSocket and IPC providers also available as web3.js packages for using. +[Providers](/guides/web3_providers_guide/) are objects 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. -:::warning -You must initialize the `Web3` object with a provider, otherwise, you won't be able to fully use web3.js functionalities. Here is an example of creating a `web3` instance with an HTTP provider: -::: +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'; @@ -62,7 +61,7 @@ web3.eth.getBlockNumber().then(console.log); ``` ## Querying the blockchain -After instantiating the `web3` instance with a `new Web3 provider`, we can access the `web3.eth` package to fetch data from 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: ```ts // get the balance of an address @@ -88,11 +87,13 @@ await web3.eth.getGasPrice(); ## Setting up a wallet -If you want to write data/interact with contracts or send transactions on the blockchain, you must have an account with funds to cover the gas fees. +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 object `Wallet` is an array of accounts, it will allow you to hold several accounts from which you can send transactions `web3.eth.sendTransaction` or interact with contract objects `web3.eth.contract.methods.contractfunction().send()`, when you perform these actions, the `Wallet` object uses the account/s it holds to send the transactions. +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 random wallet +### 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 @@ -118,7 +119,13 @@ Wallet(1) */ ``` -### Add a private key to create a wallet +### 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. + +:::warning +Private keys are sensitive data and should be treated as such. Make sure that private keys are kept private, which includes making sure they are not committed to code repositories. +::: ```ts //the private key must start with the '0x' prefix @@ -131,9 +138,11 @@ console.log(account[0].privateKey); //↳ 0x50d349f5cf627d44858d6fcb6fbf15d27457d35c58ba2d5cfeaf455f25db5bec ``` -### Send transactions +### Transfer ETH + +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 title='Sending value' +```ts //add an account to a wallet const account = web3.eth.accounts.wallet.add('0x50d349f5cf627d44858d6fcb6fbf15d27457d35c58ba2d5cfeaf455f25db5bec'); @@ -155,15 +164,18 @@ console.log('Tx hash:', txReceipt.transactionHash) ## 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 -The first step to interact with a contract is to instantiate the contract, for which we will need the ABI and the address of the 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 address in 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 const ABI = [ { @@ -178,11 +190,13 @@ const ABI = }, ]; -//instantiate the 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 @@ -196,13 +210,11 @@ const totalSupply = await uniswapToken.methods.totalSupply().call(); console.log('Uniswap Total supply:', totalSupply); // ↳ Uniswap Total Supply: 1000000000000000000000000000n - -//use web3 utils to format the units -console.log(web3.utils.fromWei(totalSupply, 'ether')) -// ↳ 1000000000 ``` -### Writing-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 @@ -220,6 +232,8 @@ console.log('Tx hash:',txReceipt.transactionHash); ### 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 const eventTransfer = await uniswapToken.getPastEvents('Transfer', { fromBlock: 18850576 }); @@ -229,10 +243,12 @@ console.log(eventTransfer); //you can only query logs from the previous 100_000 blocks ``` -### Listening to live events +### Subscribing to events -:::warning -You MUST initialize the `Web3 provider` with a WebSocket endpoint to subscribe to live 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: + +:::note +You MUST initialize the `Web3` object with a [WebSocket](/guides/web3_providers_guide/#websocket-provider) provider to subscribe to live events. ::: ```ts