From bdfe9d4a57b3ec21eae87ba49108fa32193fbc9d Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Wed, 22 May 2024 09:37:51 -0700 Subject: [PATCH 1/5] fix(docs): intro - landing page should be Introduction as opposed to Quickstart - improvements to Introduction --- .../guides/getting_started/getting_started.md | 1 - .../guides/getting_started/introduction.md | 26 ++++++++++--------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/docs/guides/getting_started/getting_started.md b/docs/docs/guides/getting_started/getting_started.md index 18b95035957..d023e01bb9f 100644 --- a/docs/docs/guides/getting_started/getting_started.md +++ b/docs/docs/guides/getting_started/getting_started.md @@ -1,5 +1,4 @@ --- -slug: / sidebar_position: 2 sidebar_label: Quickstart --- diff --git a/docs/docs/guides/getting_started/introduction.md b/docs/docs/guides/getting_started/introduction.md index ab9a303fc84..688ccb10c1d 100644 --- a/docs/docs/guides/getting_started/introduction.md +++ b/docs/docs/guides/getting_started/introduction.md @@ -1,26 +1,28 @@ --- +slug: / sidebar_position: 1 sidebar_label: Introduction --- # Introduction -Welcome to Web3.js Documentation!👋 +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**) using **HTTP, IPC or WebSocket.** It is a powerful and efficient toolkit for crafting applications within the Ethereum ecosystem and beyond. -Web3.js is a robust and flexible collection of libraries for **TypeScript and JavaScript** developers. It allows you to interact with a local or remote Ethereum node (or **any EVM-compatible blockchain**) using **HTTP, IPC or WebSocket.** It serves as an essential tool for connecting and crafting applications within the Ethereum ecosystem. - -The following documentation will guide you through different use cases of Web3.js, upgrading from older versions, as well as providing an API reference documentation with examples. +This documentation is the entrypoint to Web3.js for developers. It covers [basic](/guides/getting_started/) and [advanced](/guides/smart_contracts/) usage with examples, and includes comprehensive [API documentation](/api) as well as guides for common tasks, like [upgrading](/guides/web3_upgrade_guide/x/) from older versions. ## Features of Web3.js v4 -- Web3.js [Plugins Feature](/guides/web3_plugin_guide/) for extending functionality ( [List of Existing Plugins](https://web3js.org/plugins) ) -- ECMAScript (ESM) and CommonJS (CJS) builds -- [Tree shakable with ESM](/guides/advanced/tree_shaking) -- [Contracts dynamic types](/guides/smart_contracts/infer_contract_types/) & full API in TypeScript -- Using native BigInt instead of large BigNumber libraries -- More efficient ABI Encoder & Decoder -- Custom Output formatters -- In compliance with Eth EL API +- Flexible + - ECMAScript (ESM) and CommonJS (CJS) builds + - [Plugins](/guides/web3_plugin_guide/) for extending functionality +- Efficient + - [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/decodeLog) +- 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 Eth EL API ## Packages From 872723f8d00a88fe989146812674470b16ddf719 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Wed, 22 May 2024 12:51:06 -0700 Subject: [PATCH 2/5] Packages Enhancements to package documentation --- .../guides/getting_started/introduction.md | 44 ++++++++++--------- .../{getting_started.md => quickstart.md} | 0 2 files changed, 23 insertions(+), 21 deletions(-) rename docs/docs/guides/getting_started/{getting_started.md => quickstart.md} (100%) diff --git a/docs/docs/guides/getting_started/introduction.md b/docs/docs/guides/getting_started/introduction.md index 688ccb10c1d..3a40beaa5f9 100644 --- a/docs/docs/guides/getting_started/introduction.md +++ b/docs/docs/guides/getting_started/introduction.md @@ -8,7 +8,7 @@ sidebar_label: 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**) using **HTTP, IPC or WebSocket.** 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/) and [advanced](/guides/smart_contracts/) usage with examples, and includes comprehensive [API documentation](/api) as well as guides for common tasks, like [upgrading](/guides/web3_upgrade_guide/x/) from older versions. +This documentation is the entrypoint to Web3.js for developers. It covers [basic](/guides/getting_started/quickstart) and [advanced](/guides/smart_contracts/) usage with examples, and includes comprehensive [API documentation](/api) as well as guides for common tasks, like [upgrading](/guides/web3_upgrade_guide/x/) from older versions. ## Features of Web3.js v4 @@ -16,8 +16,9 @@ This documentation is the entrypoint to Web3.js for developers. It covers [basic - 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 + - 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/decodeLog) - Developer-Friendly - [Dynamic contract types](/guides/smart_contracts/infer_contract_types/) & full API in TypeScript @@ -26,43 +27,44 @@ This documentation is the entrypoint to Web3.js for developers. It covers [basic ## Packages -Web3.js is modular, consisting of several packages, each serving specific functionalities. If you have specific tasks in mind, you don't need to install the entire Web3 library. Instead, selectively install the package that suits your requirements for a more efficient development experience. Here is an overview of the available packages: +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: -- [**ABI:**](/libdocs/ABI) The `web3-eth-abi` package simplifies decoding logs and parameters, encoding function calls and signatures, and inferring types for efficient Ethereum **contract interactions.** +- [**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. -- [**Accounts:**](/libdocs/Accounts) The `web3-eth-accounts` package has tools for creating Ethereum accounts/wallets and making sure transactions and data are **securely signed.** +- [**Net:**](/libdocs/Net) The `web3-net` package provides discovery and interactions for an **Ethereum node's network properties.** -- [**Contract:**](/libdocs/Contract) With the `web3-eth-Contract`, you can interact with Smart contracts. This functionality allows **communication with contracts through JavaScript or TypeScript objects**, simplifying your development and interaction processes. +- [**Accounts:**](/libdocs/Accounts) The `web3-eth-accounts` package has tools for creating Ethereum accounts and the **secure signing** of transactions and data. -- [**ENS:**](/libdocs/ENS) The `web3-eth-ens` package helps you communicate with the **Ethereum Name Service (ENS)** on the blockchain. +- [**Personal:**](/libdocs/Personal) Use `web3-eth-personal` for **direct communication about your accounts with the Ethereum node**, which streamlines account management during development. -- [**Iban:**](/libdocs/Iban) The `web3-eth-iban` package allows you to switch between **Ethereum addresses and special banking-like addresses** (IBAN or BBAN). It makes the conversion back and forth easier. + **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* -- [**Net:**](/libdocs/Net) The `web3-net` class allows you to talk about and deal with an **Ethereum node's network details.** +- [**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.**. -- [**Personal:**](/libdocs/Personal) Use `web3-eth-personal` for **direct communication with the Ethereum node about your accounts**, streamlining account management in your development workflow. - **NOTE:** *For enhanced security when interacting with public nodes, consider using `web3-eth-accounts` for local signing operations, keeping your private keys and sensitive information secure on your local machine* +- [**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. -- [**Utils:**](/libdocs/Utils) With the `web3-utils` package you can perform a range of essential tasks in Ethereum development, including **converting data formats, checking addresses, encoding and decoding, hashing, handling numbers, and much more**, providing versatile utility functions for your applications. +- [**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.** -- [**Web3Eth:**](/libdocs/Web3Eth) The `web3-eth` is your main tool for interacting with the Ethereum blockchain. It's like the control center for managing your interactions with Ethereum. +- [**ENS:**](/libdocs/ENS) The `web3-eth-ens` package makes it easy for developers to communicate with the **Ethereum Name Service (ENS).** -### Additional supporting packages +- [**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. -- **Web3 Types:** This package has common typescript types. +### Additional supporting packages -- **Web3 Validator:** This package offers functionality for validation using provided Schema. +- [**Web3 Core:**](/api/web3-core) subscriptions, request management, and configuration used by other Web3 packages -- **Web3 Core:** Web3 Core has configuration, Subscriptions and Requests management functionality used by other Web3 packages. +- [**Web3 Types:**](/api/web3-types) common TypeScript types -- **Web3 Errors:** Web3 Errors has error codes and common error classes that are used by other Web3 packages. +- [**Web3 Validator:**](/api/web3-validator) runtime type validation against predefined types or custom schemas -- **Web3 RPC Methods:** This is for advanced uses for building more lightweight applications. It has functions for making RPC requests to Ethereum using a given provider. +- [**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 ## Advantages over other libraries -- **Extensive Documentation and Community**: Being one of the earliest Ethereum libraries, Web3.js 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. +- **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, meaning it allows developers to use specific packages according to their needs. This may lead to smaller bundle sizes and faster load times for web applications. +- **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. diff --git a/docs/docs/guides/getting_started/getting_started.md b/docs/docs/guides/getting_started/quickstart.md similarity index 100% rename from docs/docs/guides/getting_started/getting_started.md rename to docs/docs/guides/getting_started/quickstart.md From 003a8cb19b0e3c95d0f96b859317358ec78e5812 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Wed, 22 May 2024 12:57:24 -0700 Subject: [PATCH 3/5] Tweaks --- docs/docs/guides/getting_started/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/guides/getting_started/introduction.md b/docs/docs/guides/getting_started/introduction.md index 3a40beaa5f9..713b7362d60 100644 --- a/docs/docs/guides/getting_started/introduction.md +++ b/docs/docs/guides/getting_started/introduction.md @@ -6,7 +6,7 @@ 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**) using **HTTP, IPC or WebSocket.** It is a powerful and efficient toolkit for crafting applications within the Ethereum ecosystem and beyond. +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/) usage with examples, and includes comprehensive [API documentation](/api) as well as guides for common tasks, like [upgrading](/guides/web3_upgrade_guide/x/) from older versions. @@ -23,7 +23,7 @@ This documentation is the entrypoint to Web3.js for developers. It covers [basic - 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 Eth EL API + - In compliance with the [Ethereum JSON-RPC Specification](https://ethereum.github.io/execution-apis/api-documentation/) ## Packages From 9d3269778bd9bfc191bd87948418d7f97332f452 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Thu, 23 May 2024 05:56:31 -0700 Subject: [PATCH 4/5] @luu-alex suggestion --- docs/docs/guides/getting_started/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guides/getting_started/introduction.md b/docs/docs/guides/getting_started/introduction.md index 713b7362d60..df6b11665d2 100644 --- a/docs/docs/guides/getting_started/introduction.md +++ b/docs/docs/guides/getting_started/introduction.md @@ -53,7 +53,7 @@ Web3.js is a modular collection of packages, each of which serves a specific nee - [**Web3 Core:**](/api/web3-core) subscriptions, request management, and configuration used by other Web3 packages -- [**Web3 Types:**](/api/web3-types) common TypeScript types +- [**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 From c58821fe23505df253eb8fe31f50ce9624887bb4 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Thu, 23 May 2024 05:56:50 -0700 Subject: [PATCH 5/5] Update docs/docs/guides/getting_started/introduction.md Co-authored-by: Alex --- docs/docs/guides/getting_started/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guides/getting_started/introduction.md b/docs/docs/guides/getting_started/introduction.md index df6b11665d2..0e92051b4ce 100644 --- a/docs/docs/guides/getting_started/introduction.md +++ b/docs/docs/guides/getting_started/introduction.md @@ -19,7 +19,7 @@ This documentation is the entrypoint to Web3.js for developers. It covers [basic - 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/decodeLog) + - 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)