Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(docs): formatting #7072

Merged
merged 2 commits into from
Jun 4, 2024
Merged

chore(docs): formatting #7072

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b76cd7f
Formatting fixes for recently updated pages
danforbes May 30, 2024
f76d955
Merge branch '4.x' into chore/docs/formatting
danforbes Jun 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/docs/guides/getting_started/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.

Expand Down
75 changes: 39 additions & 36 deletions docs/docs/guides/getting_started/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

<iframe width="100%" height="700px" src="https://stackblitz.com/edit/vitejs-vite-aksddx?embed=1&file=main.js&showSidebar=1"></iframe>

Expand Down Expand Up @@ -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.

Expand All @@ -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:

Expand All @@ -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)
Expand All @@ -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.

Expand All @@ -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);
Expand All @@ -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 =
[
{
Expand All @@ -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:

Expand All @@ -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
```
Loading
Loading