Skip to content

Commit

Permalink
Restructure Docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@danforbes
danforbes committed Oct 3, 2024
1 parent dcd9d6a commit 59c7469
Show file tree
Hide file tree
Showing 78 changed files with 3,459 additions and 3,461 deletions.
26 changes: 13 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ yarn add web3

## Migration Guide

- [Migration Guide from Web3.js 1.x to 4.x](https://docs.web3js.org/guides/web3_upgrade_guide/x/)
- [Migration Guide from Web3.js 1.x to 4.x](https://docs.web3js.org/guides/web3_upgrade_guide/index)
Breaking changes are listed in migration guide and its first step for migrating from Web3.js 1.x to 4.x. If there is any question or discussion feel free to ask in [Discord](https://discord.gg/yjyvFRP), and in case of any bug or new feature request [open issue](https://github.com/web3/web3.js/issues/new) or create a pull request for [contributions](https://github.com/web3/web3.js/blob/4.x/.github/CONTRIBUTING.md).

## Useful links
Expand Down Expand Up @@ -76,18 +76,18 @@ yarn add web3

## Package.json Scripts

| Script | Description |
| ---------------- |--------------------------------------------------------------------|
| clean | Uses `rimraf` to remove `dist/` |
| build | Uses `tsc` to build all packages |
| lint | Uses `eslint` to lint all packages |
| lint:fix | Uses `eslint` to check and fix any warnings |
| format | Uses `prettier` to format the code |
| test | Uses `jest` to run unit tests in each package |
| test:integration | Uses `jest` to run tests under `/test/integration` in each package |
| test:unit | Uses `jest` to run tests under `/test/unit` in each package |
| test:manual:long-connection-ws | Runs manual tests for keeping a long WebSocket connection |
| test:manual | Runs manual tests under `test/manual` in the web3 package |
| Script | Description |
| ------------------------------ | ------------------------------------------------------------------ |
| clean | Uses `rimraf` to remove `dist/` |
| build | Uses `tsc` to build all packages |
| lint | Uses `eslint` to lint all packages |
| lint:fix | Uses `eslint` to check and fix any warnings |
| format | Uses `prettier` to format the code |
| test | Uses `jest` to run unit tests in each package |
| test:integration | Uses `jest` to run tests under `/test/integration` in each package |
| test:unit | Uses `jest` to run tests under `/test/unit` in each package |
| test:manual:long-connection-ws | Runs manual tests for keeping a long WebSocket connection |
| test:manual | Runs manual tests under `test/manual` in the web3 package |

[npm-url]: https://npmjs.org/package/web3
[downloads-image]: https://img.shields.io/npm/dm/web3?label=npm%20downloads
81 changes: 45 additions & 36 deletions docs/docs/glossary/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ sidebar_label: '📖 Glossary'
title: Glossary
---


## Provider

In web3.js, a `provider` is an object responsible for enabling connectivity with the Ethereum network in various ways. Providers facilitate the connection of your web application to an Ethereum node, different provider types are available in web3.js(HTTP, WebSocket and IPC), each with its own features and use cases. **It's important to note that a provider itself only provides read-only access to the blockchain.** It does not use any private keys or accounts for interaction. This read-only functionality is particularly useful for querying data and making calls to the blockchain without the need for private key authorization.
Expand All @@ -13,12 +12,10 @@ In web3.js, a `provider` is an object responsible for enabling connectivity with

In web3.js, an `account` allows you to perform operations on the blockchain, such as sending transactions, signing data, and interacting with contracts. It serves as the key component for **using a private key** directly to execute various blockchain operations. In other libraries, this concept is often referred to as a `signer`. This versatility in terminology doesn't change its fundamental purpose, providing a secure and straightforward means to manage Ethereum-related operations.


## Wallet

A `wallet` in web3.js can store multiple `accounts`. This feature allows you to manage various private keys for different operations. When using methods such as `web3.eth.sendTransaction()` or `web3.eth.contract.methods.doSomething().send({})`, the web3.js library handles these transactions using the wallet accounts under the hood. Essentially, the wallet makes it easier to coordinate multiple accounts for smoother Ethereum operations.


## Contract

The `Contract` class is an important class in the `web3-eth-contract` package, also available in the `web3` package. It serves as an abstraction representing a connection to a specific contract on the Ethereum Network, enabling applications to interact with it as a typical JavaScript object. Through the `Contract` class, you can execute functions and listen to events associated with the smart contract (e.g, `contract.methods.doSomething().call()`)
Expand Down Expand Up @@ -82,30 +79,39 @@ contract Test {

```json title='Resulting JSON ABI'
[
{
"type": "constructor",
"stateMutability": "nonpayable",
"inputs": [{"internalType":"uint256","name":"testInt","type":"uint256"}],
},
{
"type": "event",
"name": "Event",
"inputs": [{"indexed":true,"internalType":"uint256","name":"b","type":"uint256"},{"indexed":false,"internalType":"bytes32","name":"c","type":"bytes32"}],
"anonymous": false,
},
{
"type": "event",
"name": "Event2",
"inputs": [{"indexed":true,"internalType":"uint256","name":"b","type":"uint256"},{"indexed":false,"internalType":"bytes32","name":"c","type":"bytes32"}],
"anonymous": false,
},
{
"type": "function",
"name": "foo",
"stateMutability": "nonpayable",
"inputs": [{"internalType":"uint256","name":"b","type":"uint256"},{"internalType":"bytes32","name":"c","type":"bytes32"}],
"outputs": [{"internalType":"address","name":"","type":"address"}],
}
{
"type": "constructor",
"stateMutability": "nonpayable",
"inputs": [{ "internalType": "uint256", "name": "testInt", "type": "uint256" }]
},
{
"type": "event",
"name": "Event",
"inputs": [
{ "indexed": true, "internalType": "uint256", "name": "b", "type": "uint256" },
{ "indexed": false, "internalType": "bytes32", "name": "c", "type": "bytes32" }
],
"anonymous": false
},
{
"type": "event",
"name": "Event2",
"inputs": [
{ "indexed": true, "internalType": "uint256", "name": "b", "type": "uint256" },
{ "indexed": false, "internalType": "bytes32", "name": "c", "type": "bytes32" }
],
"anonymous": false
},
{
"type": "function",
"name": "foo",
"stateMutability": "nonpayable",
"inputs": [
{ "internalType": "uint256", "name": "b", "type": "uint256" },
{ "internalType": "bytes32", "name": "c", "type": "bytes32" }
],
"outputs": [{ "internalType": "address", "name": "", "type": "address" }]
}
]
```

Expand All @@ -123,6 +129,7 @@ const web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'));
```

## WebSocketProvider

[WebSocketProvider](https://docs.web3js.org/guides/web3_providers_guide/#websocket-provider) in Web3.js connects your application to an Ethereum node via WebSocket, enabling real-time and asynchronous communication. This provider is ideal for applications needing real-time updates, such as new blocks or smart contract events. It offers better performance for high-throughput applications compared to `HttpProvider`. Ensure secure connections with `wss://` for exposed endpoints. Handle reconnections gracefully for reliable operation.

```javascript title='WebSocketProvider example'
Expand All @@ -138,13 +145,14 @@ The `Events` class in Web3.js is a crucial part of the library that enables deve

```solidity title='Event in solidity'
contract MyContract {
event Transfer(address indexed from, address indexed to, uint value);
event Transfer(address indexed from, address indexed to, uint256 value);
function transfer(address recipient, uint amount) public {
// ... transfer logic ...
emit Transfer(msg.sender, recipient, amount);
}
function transfer(address recipient, uint256 amount) public {
// ... transfer logic ...
emit Transfer(msg.sender, recipient, amount);
}
}
```

```javascript title='Event in web3.js'
Expand All @@ -158,9 +166,9 @@ const myContract = new web3.eth.Contract(MyContract.abi, contractAddress);

const transferEvent = myContract.events.Transfer(); // Access the Transfer event

transferEvent.on('data', (event) => {
console.log('Transfer Event:', event);
// Process the event data (from, to, value)
transferEvent.on('data', event => {
console.log('Transfer Event:', event);
// Process the event data (from, to, value)
});
```

Expand Down Expand Up @@ -190,4 +198,5 @@ web3.eth.getPastLogs(options)
.catch((error) => {
console.error('Error retrieving logs:', error);
});
`
`
```
0 ...ocs/guides/getting_started/_category_.yml → .../guides/01_getting_started/_category_.yml
View file
File renamed without changes.
92 changes: 92 additions & 0 deletions docs/docs/guides/01_getting_started/introduction.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
slug: /
sidebar_position: 1
sidebar_label: Introduction
---

# Introduction

Web3.js is a robust and flexible collection of **TypeScript and JavaScript** libraries that allows developers to interact with local or remote [Ethereum](https://ethereum.org/en/) nodes (or **any EVM-compatible blockchain**) over **HTTP, IPC or WebSocket** connections. It is a powerful and efficient toolkit for crafting applications within the Ethereum ecosystem and beyond.

This documentation is the entrypoint to Web3.js for developers. It covers [basic](/guides/getting_started/quickstart) and [advanced](/guides/smart_contracts/mastering_smart_contracts) usage with examples, and includes comprehensive [API documentation](/api) as well as guides for common tasks, like [upgrading](/guides/web3_upgrade_guide) from older versions.

## Features of Web3.js v4

- Flexible
- ECMAScript (ESM) and CommonJS (CJS) builds
- [Plugins](/guides/web3_plugin_guide/) for extending functionality
- Efficient
- Modular, [package](/#packages)-based design reduces unneeded dependencies
- [Tree shakable with ESM](/guides/advanced/tree_shaking)
- Use of native [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) (instead of large [BigNumber](https://mikemcl.github.io/bignumber.js/) libraries)
- Efficient ABI [encoding](/api/web3-eth-abi/function/encodeFunctionCall) & [decoding](/api/web3-eth-abi/function/decodeParameter)
- Developer-Friendly
- [Dynamic contract types](/guides/smart_contracts/infer_contract_types/) & full API in TypeScript
- Custom output [formatters](https://docs.web3js.org/api/web3-utils/function/format)
- In compliance with the [Ethereum JSON-RPC Specification](https://ethereum.github.io/execution-apis/api-documentation/)

## Using These Docs

There is a lot to learn about Web3.js! Here are some tips for developers of different skill levels. Remember, you can always [reach out directly](/guides/feedback/#urgent-questions-or-concerns) with Discord or Twitter if you're feeling stuck.

### For Beginner Web3.js Developers

New Web3.js developers should proceed to the [Quickstart](/guides/getting_started/quickstart) section to learn how to get started with Web3.js. Once you understand the basics, you may want to consider learning more about [providers](/guides/web3_providers_guide/), [wallets and accounts](/guides/wallet), [smart contracts](/guides/smart_contracts/smart_contracts_guide), and how to [use Web3.js with the Hardhat development environment](/guides/hardhat_tutorial).

### For Intermediate & Advanced Web3.js Developers

If you're already familiar with Ethereum and Web3.js development, you may want to review the Web3.js [package structure](#packages--plugins) and proceed directly to the [package-level documentation](/libdocs/ABI) and [API documentation](/api). Application developers may wish to review the [Web3.js configuration guide](/guides/web3_config) or learn how to use Web3.js with tools like the [MetaMask](/guides/dapps/metamask-react) wallet or the [WalletConnect](/guides/dapps/web3_modal_guide) wallet selection modal. Don't forget to review the [list of available plugins](https://web3js.org/plugins) or even [learn how to build your own Web3.js plugin](/guides/web3_plugin_guide/plugin_authors)!

## Packages & Plugins

Web3.js is a modular collection of packages, each of which serves a specific needs. This means developers don't need to install the entire Web3 library for most use cases. Instead, necessary packages are selectively installed for a more efficient development experience. Here is an overview of a selection of available packages:

- [**Web3Eth:**](/libdocs/Web3Eth) The `web3-eth` package is the entrypoint to Web3.js - it's the control center for managing interactions with Ethereum and other EVM-compatible networks.

- [**Net:**](/libdocs/Net) The `web3-net` package provides discovery and interactions for an **Ethereum node's network properties.**

- [**Accounts:**](/libdocs/Accounts) The `web3-eth-accounts` package has tools for creating Ethereum accounts and the **secure signing** of transactions and data.

- [**Personal:**](/libdocs/Personal) Use `web3-eth-personal` for **direct communication about your accounts with the Ethereum node**, which streamlines account management during development.

**NOTE:** _For enhanced security in production and when interacting with public nodes, consider using `web3-eth-accounts` for local signing operations, which keeps your private keys and sensitive information secure on your local machine_

- [**Utils:**](/libdocs/Utils) The `web3-utils` package provides helpers to perform a range of essential Ethereum development tasks, including **converting data formats, checking addresses, encoding and decoding data, hashing, handling numbers, and much more.**.

- [**Contract:**](/libdocs/Contract) The `web3-eth-contract` package makes it easy to **interact with smart contracts through JavaScript or TypeScript,** which streamlines the development process and makes it less error-prone.

- [**ABI:**](/libdocs/ABI) The `web3-eth-abi` package simplifies decoding logs and parameters, encoding function calls and signatures, and inferring types for efficient Ethereum **smart contract interactions.**

- [**ENS:**](/libdocs/ENS) The `web3-eth-ens` package makes it easy for developers to communicate with the **Ethereum Name Service (ENS).**

- [**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

- [**Web3 Core:**](/api/web3-core) subscriptions, request management, and configuration used by other Web3 packages

- [**Web3 Types:**](/api/web3-types) data structures, objects, interfaces and types used by Web3

- [**Web3 Validator:**](/api/web3-validator) runtime type validation against predefined types or custom schemas

- [**Web3 Errors:**](/api/web3-errors) error codes and common error classes that are used by other Web3 packages

- [**Web3 RPC Methods:**](/api/web3/namespace/rpcMethods) functions for making RPC requests to Ethereum using a given 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:

- [EIP-4337 (Account Abstraction) Plugin](https://www.npmjs.com/package/@chainsafe/web3-plugin-eip4337)

- [EIP-4844 (Blob Transactions) Plugin](https://www.npmjs.com/package/web3-plugin-blob-tx)

- [zkSync Plugin](https://www.npmjs.com/package/web3-plugin-zksync)

## 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.

- **Modular Design**: Web3.js is designed to be modular, which allows developers to use specific packages according to their needs. This leads to smaller bundle sizes and faster load times for web applications.

- **Active Development and Support**: Web3.js sees regular updates and active development. This support is crucial for developers needing assurance that the library they're using will keep pace with the evolving Ethereum landscape.
Loading

0 comments on commit 59c7469

Please sign in to comment.