From 92caae200e173539854785ce70b284c74e0a067d Mon Sep 17 00:00:00 2001 From: SantiagoDevRel Date: Tue, 26 Mar 2024 22:03:43 +0000 Subject: [PATCH 1/6] renamed to getting started --- docs/docs/guides/web3_plugin_guide/_category_.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guides/web3_plugin_guide/_category_.yml b/docs/docs/guides/web3_plugin_guide/_category_.yml index afd1de17e96..daec6ebe046 100644 --- a/docs/docs/guides/web3_plugin_guide/_category_.yml +++ b/docs/docs/guides/web3_plugin_guide/_category_.yml @@ -1,4 +1,4 @@ -label: '🧩🛠️ Web3 Plugin' +label: '🛠️ Web3 Plugin🧩' collapsible: true collapsed: true link: null From 253f91160dfc200d950fa0c98af108453a6892c5 Mon Sep 17 00:00:00 2001 From: SantiagoDevRel Date: Tue, 26 Mar 2024 22:04:10 +0000 Subject: [PATCH 2/6] added eth and utils example --- docs/docs/guides/web3_plugin_guide/index.md | 87 +++++++++++++-------- 1 file changed, 55 insertions(+), 32 deletions(-) diff --git a/docs/docs/guides/web3_plugin_guide/index.md b/docs/docs/guides/web3_plugin_guide/index.md index 365ca7b82f1..e20e3b9fde8 100644 --- a/docs/docs/guides/web3_plugin_guide/index.md +++ b/docs/docs/guides/web3_plugin_guide/index.md @@ -1,50 +1,73 @@ --- sidebar_position: 1 -sidebar_label: 'Introduction' +sidebar_label: 'Getting started' --- -# Introduction +# Getting Started Welcome to the web3.js Plugins Guide, an exciting new feature introduced in web3.js v4! In addition to the core web3.js libraries, plugins bring specialized functionalities tailored for end-users (functionalities that you, as a developer, can create). These enhancements may involve creating wrappers for specific contracts, adding extra features to RPC methods, or extending the capabilities of web3.js methods. Dive in and explore this innovative addition to web3.js v4! - [Plugin Developer Guide (For Creators)](/guides/web3_plugin_guide/plugin_authors) - [Plugin User Guide (Usage)](/guides/web3_plugin_guide/plugin_users) -- [Plugin List](https://web3js.org/plugins) +- You can find all the web3 plugins🧩 [here](https://web3js.org/plugins) -## Plugin Showcase +- To list your web3 plugin🧩 into the web3js.org/plugins page, you can submit a PR [here](https://github.com/web3/web3js-landing/blob/main/src/pluginList.ts) -### Chainlink Plugin -- [`npm i @chainsafe/web3-plugin-chainlink`](https://www.npmjs.com/package/@chainsafe/web3-plugin-chainlink) -- **Description**: A Web3.js 4.x Plugin for Interacting With Chainlink Smart Contracts -- **Author**: ChainSafe Systems +## Create a plugin -### Tokens Plugin -- [`npm i @chainsafe/web3-plugin-tokens`](https://www.npmjs.com/package/@chainsafe/web3-plugin-tokens) -- **Description**: Plugin to extend web3.js with additional methods to interact with common token interfaces (ERC20, ERC721, ERC1155...) -- **Author**: Peter Grassberger & ChainSafe +```javascript +//1. import the `Web3PluginBase` module +const { Web3PluginBase } = require("web3"); -### Craftsman Plugin -- [`npm i web3-plugin-craftsman`](https://www.npmjs.com/package/web3-plugin-craftsman) -- **Description**: web3.js plugin allowing instantiation of contract objects directly from Solidity source code -- **Author**: Muhammad-Altabba +//2. Create a Class extending the `Web3Pluginbase` +class MyPlugin extends Web3PluginBase { + + //3. Add a name to the plugin + pluginNamespace = "pluginExample"; -### Optimism Plugin -- [`npm i @eth-optimism/web3.js-plugin`](https://www.npmjs.com/package/@eth-optimism/web3.js-plugin) -- **Description**: Web3.js plugin for OP-Chain gas estimation -- **Author**: Unknown + //4. Createa any methods with your desired functionality + async doSomething(){ + console.log("Hello web3!"); + //send transactions + //initialize contracts + //deploy or interact with contracts + //add your own library, logic or functionality + //much more... + } +} -### Near Protocol Plugin -- [`npm i @conx3/web3-plugin-near`](https://npmjs.com/package/@conx3/web3-plugin-near) -- **Description**: web3.js plugin for Near Protocol -- **Author**: Muhammad Altabba +module.exports = MyPlugin; +``` + +## Use a plugin + +```javascript +//1. import the plugin and web3 module +const { Web3 } = require("web3"); +const MyPlugin = require("./plugin"); + +//2. Initialize the web3 instance +const web3 = new Web3("https://eth.llamarpc.com"); + +//3. Register plugin to add the current Web3Context +web3.registerPlugin(new MyPlugin()); + +//4. Use the plugin methods +web3.pluginExample.doSomething(); +//--> Hello web3! +``` + +## Using web3 packages on the plugin + +### Import eth module +Here you will find a file `plugin.js` with the plugin code and a `usage.js` file with the example usage, feel free to navigate between both files. + + + +### Import utils module +Here you will find a file `plugin.js` with the plugin code and a `usage.js` file with the example usage, feel free to navigate between both files. + + -### Aurora Engine Plugin -- [`npm i @conx3/web3-plugin-aurora`](https://www.npmjs.com/package/@conx3/web3-plugin-aurora) -- **Description**: web3.js plugin for Aurora Engine, an EVM running atop NEAR protocol -- **Author**: Muhammad Altabba -### Superfluid Plugin -- [`npm i web3-plugin-superfluid`](https://www.npmjs.com/package/web3-plugin-superfluid) -- **Description**: Superfluid Web3.js Plugin -- **Author**: Salman Dabbakuti From 3cd4b567a3f822bd7928f37ffa44ef813ff13934 Mon Sep 17 00:00:00 2001 From: SantiagoDevRel Date: Wed, 3 Apr 2024 11:56:42 +0300 Subject: [PATCH 3/6] created getting started plugin - THERE ARE SOME `TO DOs` --- docs/docs/guides/web3_plugin_guide/index.md | 210 +++++++++++++++++++- 1 file changed, 203 insertions(+), 7 deletions(-) diff --git a/docs/docs/guides/web3_plugin_guide/index.md b/docs/docs/guides/web3_plugin_guide/index.md index e20e3b9fde8..d10c44a85dc 100644 --- a/docs/docs/guides/web3_plugin_guide/index.md +++ b/docs/docs/guides/web3_plugin_guide/index.md @@ -26,7 +26,7 @@ class MyPlugin extends Web3PluginBase { //3. Add a name to the plugin pluginNamespace = "pluginExample"; - //4. Createa any methods with your desired functionality + //4. Create any methods with your desired functionality async doSomething(){ console.log("Hello web3!"); //send transactions @@ -58,16 +58,212 @@ web3.pluginExample.doSomething(); //--> Hello web3! ``` +## Initialize a provider for the plugin + +There are 2 ways to initialize a provider when you are using a plugin, the [first one](#set-a-provider-within-the-plugin) is within the plugin (internally using the `this` object and `setProvider()` method). And the [second one](#register-plugin), is done by the final user by using the `registerPlugin()` method. + +### Register plugin (External - Final user) + +When the final user (developer) is using the plugin, they must write the following: + +```js +//Step #1: Import the plugin and web3 module +const { Web3 } = require("web3"); +const MyPlugin = require("./plugin"); + +//Step #2: Initialize the web3 instance +const web3 = new Web3("https://eth.llamarpc.com"); + +//Step #3: Register plugin to add the current Web3Context +web3.registerPlugin(new MyPlugin()); +``` + +And once the plugin is registered in step #3 by using `registerPlugin(new Plugin)`, the provider in the plugin is automatically set to the provider initialized in `Step #2` (in this case: `https://eth.llamarpc.com`). + +### Set a provider within the plugin (web3Context) + +If you want to initialize the provider inside the plugin you can use the `this` object, but anyway the user must initialize a provider when [registering the plugin](#register-plugin-external---final-user): + +```js +//Step #1: Import modules +const { Web3PluginBase, eth } = require("web3"); + +//Step #2: Create class +class MyPlugin extends Web3PluginBase { + pluginNamespace = "myPlugin"; + +//Step #3: Set providers + async getChainIdMainnet() { + this.setProvider("https://eth.llamarpc.com") //or any other RPC + return await eth.getChainId(this) + } + + async getChainIdPolygon() { + this.setProvider("https://polygon.llamarpc.com") //or any other RPC + return await eth.getChainId(this) + } + + async getChainIdArbitrum() { + this.setProvider("https://arbitrum.llamarpc.com") //or any other RPC + return await eth.getChainId(this) + } +} + +``` + + + ## Using web3 packages on the plugin -### Import eth module -Here you will find a file `plugin.js` with the plugin code and a `usage.js` file with the example usage, feel free to navigate between both files. +### Use Eth module + +```js +import { FMT_NUMBER, Web3PluginBase, eth } from 'web3'; + +class MyPlugin extends Web3PluginBase { + pluginNamespace = 'pluginExample'; + + async getChainId() { + //`this` is the web3context used when you register the plugin in the usage + return await eth.getChainId(this, { number: FMT_NUMBER.NUMBER }); + } + + async getBlockNumber() { + return await eth.getBlockNumber(this, { number: FMT_NUMBER.NUMBER }); + } + + //more web3.eth. methods... +} + +export default MyPlugin; +``` + +### Use Utils + +```js +import { Web3PluginBase, utils } from 'web3'; + +class MyPlugin extends Web3PluginBase { + pluginNamespace = 'pluginExample'; + + weiToEth(value) { + //`this` is the web3context used when you register the plugin in the usage + return utils.fromWei(value, 'ether'); + } + + //more web3.eth. methods... +} + +export default MyPlugin; + +``` + + +### Use Accounts + + +```js +import { Web3PluginBase, eth } from 'web3'; + +class MyPlugin extends Web3PluginBase { + pluginNamespace = 'pluginExample'; + + async createAccount() { + const account = eth.accounts.create(); + console.log("account:", account); + /* + account: { + address: '0x59E797F2F66AffA9A419a6BC2ED4742b7cBc2570', + privateKey: '0x52a81fc3a7fd6ce9644147c9fb5bfbe1f708f37b4611b3c3310eb9a6dc85ccf4', + signTransaction: [Function: signTransaction], + sign: [Function: sign], + encrypt: [Function: encrypt] + } + */ + } +} + +export default MyPlugin; +``` + +### Use Wallet + + +```js +import { Web3PluginBase, eth } from 'web3'; + +class MyPlugin extends Web3PluginBase { + pluginNamespace = 'pluginExample'; + + async createWallet() { + //1. Create a random account + const accounts = eth.accounts.create(); + //2. Add the account to the wallet + const wallet = this.wallet.add(accounts); + //by creating the wallet, web3.js will use this account to sign TXs under the hood + console.log(wallet); + /* + Wallet(1) [ + { + address: '0x233725561B1430bE2C24Ce9EEabe63E4B46EC9E3', + privateKey: '0x6856adf06dd803e0354450ccf251f829a2c9ef1177ce371f8835bbfb56cd0898', + signTransaction: [Function: signTransaction], + sign: [Function: sign], + encrypt: [Function: encrypt] + }, + _accountProvider: { + create: [Function: createWithContext], + privateKeyToAccount: [Function: privateKeyToAccountWithContext], + decrypt: [Function: decryptWithContext] + }, + _addressMap: Map(1) { '0x233725561b1430be2c24ce9eeabe63e4b46ec9e3' => 0 }, + _defaultKeyName: 'web3js_wallet' + ] + */ + } +} + +export default MyPlugin; +``` + + +### Use Contract + + +```js +import { Web3PluginBase, Contract } from 'web3'; + +class MyPlugin extends Web3PluginBase { + pluginNamespace = 'pluginExample'; + + async interactWithContract() { + //1. Initialize contract + const myContract = new Contract(ABI, ADDRESS); + + //2. Interact with reading functions + const response = myContract.methods.doSomething().call(); + + //3. Interact with writing functions + //You must initialize a wallet to be able to send the TX from wallet[0].address + const txReceipt = myContract.methods.doSomething().send({from: wallet[0].address}) + } +} + +export default MyPlugin; +``` + +### Use ENS + +TO DO + +## Use web3Context - +TO DO -### Import utils module -Here you will find a file `plugin.js` with the plugin code and a `usage.js` file with the example usage, feel free to navigate between both files. +## Use requestManager - +TO DO +## Config Params +TO DO \ No newline at end of file From 6db5b988b43233adea2173082cc02c65fc6984e4 Mon Sep 17 00:00:00 2001 From: santiagodevrel Date: Tue, 16 Apr 2024 18:47:30 +0300 Subject: [PATCH 4/6] added other packages --- docs/docs/guides/web3_plugin_guide/index.md | 81 +++++++++++++++++++-- 1 file changed, 73 insertions(+), 8 deletions(-) diff --git a/docs/docs/guides/web3_plugin_guide/index.md b/docs/docs/guides/web3_plugin_guide/index.md index d10c44a85dc..5fc6f2b0517 100644 --- a/docs/docs/guides/web3_plugin_guide/index.md +++ b/docs/docs/guides/web3_plugin_guide/index.md @@ -5,7 +5,9 @@ sidebar_label: 'Getting started' # Getting Started -Welcome to the web3.js Plugins Guide, an exciting new feature introduced in web3.js v4! In addition to the core web3.js libraries, plugins bring specialized functionalities tailored for end-users (functionalities that you, as a developer, can create). These enhancements may involve creating wrappers for specific contracts, adding extra features to RPC methods, or extending the capabilities of web3.js methods. Dive in and explore this innovative addition to web3.js v4! +Welcome to the Web3 Plugins🧩 Guide, a new feature introduced in web3.js v4. In addition to the core web3.js libraries, plugins bring specialized functionalities tailored for end-users (functionalities, that you, as a developer, can create). These enhancements may involve creating wrappers for specific contracts, adding extra features to RPC methods, adding any external libraries, logic, extending the capabilities of web3.js methods, etc... + +In this guide, you will learn the basics to get started building web3 plugins, setting up providers, importing, and using different web3.js packages. - [Plugin Developer Guide (For Creators)](/guides/web3_plugin_guide/plugin_authors) - [Plugin User Guide (Usage)](/guides/web3_plugin_guide/plugin_users) @@ -254,16 +256,79 @@ export default MyPlugin; ### Use ENS -TO DO +```js +const { Web3PluginBase } = require("web3"); +const { ENS } = require("web3-eth-ens"); -## Use web3Context +class MyPlugin extends Web3PluginBase { + pluginNamespace = "pluginExample"; -TO DO + async getAddressENS() { + const ens = new ENS(undefined, this); //link to current web3Context + return ens.getAddress("ethereum.eth"); + } + +} + +``` +:::info +More ENS methods [here](https://docs.web3js.org/libdocs/ENS#methods) +::: -## Use requestManager -TO DO +## Web3 requestManager (custom RPC) -## Config Params +```js +import { Web3PluginBase } from 'web3'; + +class MyPlugin extends Web3PluginBase { + pluginNamespace = 'pluginExample'; + + async customRPC() { + return await this.requestManager.send({ + method: "custom_RPC_call", + params: [], + }); + } + + async getNonce() { + return await this.requestManager.send({ + jsonrpc: "2.0", + method: "eth_getTransactionCount", + params: ["0xEA9eEca67682Cd9c6Ce3DdD1681049D7A897289F", "latest"], + }); + } -TO DO \ No newline at end of file + async getBlockNumber() { + return await this.requestManager.send({ + jsonrpc: "2.0", + method: "eth_blockNumber", + params: [], + }); + } + +} +``` + +:::info +All the Ethereum JSON-RPC API [here](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount) +::: + +## Web3 Config Params + +```js +import { Web3PluginBase } from 'web3'; + +class MyPlugin extends Web3PluginBase { + pluginNamespace = 'pluginExample'; + + async configParams() { + this.config.handleRevert = true; + this.config.defaultTransactionType = 0x1; + //more params... + } +} +``` +:::info +All web3 config params [here](https://docs.web3js.org/guides/web3_config/) +::: \ No newline at end of file From e463c96b0234503e075c810eff2739ce2adae6bb Mon Sep 17 00:00:00 2001 From: santiagodevrel Date: Tue, 16 Apr 2024 21:44:06 +0300 Subject: [PATCH 5/6] changed requires for import statements --- docs/docs/guides/web3_plugin_guide/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/guides/web3_plugin_guide/index.md b/docs/docs/guides/web3_plugin_guide/index.md index 5fc6f2b0517..a276587186e 100644 --- a/docs/docs/guides/web3_plugin_guide/index.md +++ b/docs/docs/guides/web3_plugin_guide/index.md @@ -20,7 +20,7 @@ In this guide, you will learn the basics to get started building web3 plugins, s ```javascript //1. import the `Web3PluginBase` module -const { Web3PluginBase } = require("web3"); +import { Web3PluginBase } from "web3"; //2. Create a Class extending the `Web3Pluginbase` class MyPlugin extends Web3PluginBase { @@ -46,8 +46,8 @@ module.exports = MyPlugin; ```javascript //1. import the plugin and web3 module -const { Web3 } = require("web3"); -const MyPlugin = require("./plugin"); +import { Web3 } from "web3"; +import MyPlugin from "./plugin"; //2. Initialize the web3 instance const web3 = new Web3("https://eth.llamarpc.com"); @@ -70,8 +70,8 @@ When the final user (developer) is using the plugin, they must write the followi ```js //Step #1: Import the plugin and web3 module -const { Web3 } = require("web3"); -const MyPlugin = require("./plugin"); +import { Web3 } from "web3"; +import MyPlugin from "./plugin"; //Step #2: Initialize the web3 instance const web3 = new Web3("https://eth.llamarpc.com"); @@ -88,7 +88,7 @@ If you want to initialize the provider inside the plugin you can use the `this` ```js //Step #1: Import modules -const { Web3PluginBase, eth } = require("web3"); +import { Web3PluginBase, eth } from "web3"; //Step #2: Create class class MyPlugin extends Web3PluginBase { @@ -257,8 +257,8 @@ export default MyPlugin; ### Use ENS ```js -const { Web3PluginBase } = require("web3"); -const { ENS } = require("web3-eth-ens"); +import { Web3PluginBase } from "web3"; +import { ENS } from "web3-eth-ens"; class MyPlugin extends Web3PluginBase { pluginNamespace = "pluginExample"; From 08828378ab44d6e189a44676634695c85437c540 Mon Sep 17 00:00:00 2001 From: santiagodevrel Date: Mon, 22 Apr 2024 21:22:43 +0300 Subject: [PATCH 6/6] removed initialize a provider --- docs/docs/guides/web3_plugin_guide/index.md | 55 --------------------- 1 file changed, 55 deletions(-) diff --git a/docs/docs/guides/web3_plugin_guide/index.md b/docs/docs/guides/web3_plugin_guide/index.md index a276587186e..0e23b5a85e7 100644 --- a/docs/docs/guides/web3_plugin_guide/index.md +++ b/docs/docs/guides/web3_plugin_guide/index.md @@ -60,61 +60,6 @@ web3.pluginExample.doSomething(); //--> Hello web3! ``` -## Initialize a provider for the plugin - -There are 2 ways to initialize a provider when you are using a plugin, the [first one](#set-a-provider-within-the-plugin) is within the plugin (internally using the `this` object and `setProvider()` method). And the [second one](#register-plugin), is done by the final user by using the `registerPlugin()` method. - -### Register plugin (External - Final user) - -When the final user (developer) is using the plugin, they must write the following: - -```js -//Step #1: Import the plugin and web3 module -import { Web3 } from "web3"; -import MyPlugin from "./plugin"; - -//Step #2: Initialize the web3 instance -const web3 = new Web3("https://eth.llamarpc.com"); - -//Step #3: Register plugin to add the current Web3Context -web3.registerPlugin(new MyPlugin()); -``` - -And once the plugin is registered in step #3 by using `registerPlugin(new Plugin)`, the provider in the plugin is automatically set to the provider initialized in `Step #2` (in this case: `https://eth.llamarpc.com`). - -### Set a provider within the plugin (web3Context) - -If you want to initialize the provider inside the plugin you can use the `this` object, but anyway the user must initialize a provider when [registering the plugin](#register-plugin-external---final-user): - -```js -//Step #1: Import modules -import { Web3PluginBase, eth } from "web3"; - -//Step #2: Create class -class MyPlugin extends Web3PluginBase { - pluginNamespace = "myPlugin"; - -//Step #3: Set providers - async getChainIdMainnet() { - this.setProvider("https://eth.llamarpc.com") //or any other RPC - return await eth.getChainId(this) - } - - async getChainIdPolygon() { - this.setProvider("https://polygon.llamarpc.com") //or any other RPC - return await eth.getChainId(this) - } - - async getChainIdArbitrum() { - this.setProvider("https://arbitrum.llamarpc.com") //or any other RPC - return await eth.getChainId(this) - } -} - -``` - - - ## Using web3 packages on the plugin ### Use Eth module