Web3.js¶

Warning

Web3.js has been sunset. You can find guides on using Ethers.js and viem in the Libraries section.

Introduction¶

Interacting with blockchains typically requires an interface between your application and the network. Web3.js offers this interface through a comprehensive collection of libraries, facilitating seamless interaction with the nodes using HTTP or WebSocket protocols. This guide illustrates how to utilize Web3.js specifically for interactions with Polkadot Hub.

This guide is intended for developers who are familiar with JavaScript and want to interact with the Polkadot Hub using Web3.js.

Prerequisites¶

Before getting started, ensure you have the following installed:

Node.js: v22.13.1 or later, check the Node.js installation guide.
npm: v6.13.4 or later (comes bundled with Node.js).
Solidity: This guide uses Solidity ^0.8.9 for smart contract development.

Project Structure¶

This project organizes contracts, scripts, and compiled artifacts for easy development and deployment.

web3js-project
├── contracts
│   ├── Storage.sol
├── scripts
│   ├── connectToProvider.js
│   ├── fetchLastBlock.js
│   ├── compile.js
│   ├── deploy.js
│   ├── updateStorage.js
├── abis
│   ├── Storage.json
├── artifacts
│   ├── Storage.bin
├── contract-address.json
├── node_modules/
├── package.json
├── package-lock.json
└── README.md

Set Up the Project¶

To start working with Web3.js, create a new folder and initialize your project by running the following commands in your terminal:

mkdir web3js-project
cd web3js-project
npm init -y

Install Dependencies¶

Next, run the following command to install the Web3.js library:

npm install web3

Add the Solidity compiler so you can generate standard EVM bytecode:

npm install --save-dev solc

Set Up the Web3 Provider¶

The provider configuration is the foundation of any Web3.js application. It serves as a bridge between your application and the blockchain, allowing you to query blockchain data and interact with smart contracts.

To interact with Polkadot Hub, you must set up a Web3.js provider. This provider connects to a blockchain node, allowing you to query blockchain data and interact with smart contracts. In the scripts directory of your project, create a file named connectToProvider.js and add the following code:

scripts/connectToProvider.js

const { Web3 } = require('web3');

const createProvider = (rpcUrl) => {
  const web3 = new Web3(rpcUrl);
  return web3;
};

const PROVIDER_RPC = {
  rpc: 'INSERT_RPC_URL',
  chainId: 'INSERT_CHAIN_ID',
  name: 'INSERT_CHAIN_NAME',
};

createProvider(PROVIDER_RPC.rpc);

Note

Replace INSERT_RPC_URL, INSERT_CHAIN_ID, and INSERT_CHAIN_NAME with the appropriate values. For example, to connect to Polkadot Hub TestNet's Ethereum RPC instance, you can use the following parameters:

const PROVIDER_RPC = {
  rpc: 'https://services.polkadothub-rpc.com/testnet',
  chainId: 420420417,
  name: 'polkadot-hub-testnet'
};

To connect to the provider, execute:

node scripts/connectToProvider.js

With the provider set up, you can start querying the blockchain. For instance, to fetch the latest block number.

Fetch last block example

scripts/fetchLastBlock.js

const { Web3 } = require('web3');

const createProvider = (rpcUrl) => {
  const web3 = new Web3(rpcUrl);
  return web3;
};

const PROVIDER_RPC = {
  rpc: 'https://services.polkadothub-rpc.com/testnet',
  chainId: 420420417,
  name: 'polkadotTestNet',
};

const main = async () => {
  try {
    const web3 = createProvider(PROVIDER_RPC.rpc);
    const latestBlock = await web3.eth.getBlockNumber();
    console.log('Last block: ' + latestBlock);
  } catch (error) {
    console.error('Error connecting to Polkadot Hub TestNet: ' + error.message);
  }
};

main();

Compile Contracts¶

Polkadot Hub exposes an Ethereum JSON-RPC endpoint, so you can compile Solidity contracts to familiar EVM bytecode with the upstream solc compiler. The resulting artifacts work with any EVM-compatible toolchain and can be deployed through Web3.js.

Sample Storage Smart Contract¶

This example demonstrates compiling a Storage.sol Solidity contract for deployment to Polkadot Hub. The contract's functionality stores a number and permits users to update it with a new value.

contracts/Storage.sol

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.9;

contract Storage {
    // Public state variable to store a number
    uint256 public storedNumber;

    /**
    * Updates the stored number.
    *
    * The `public` modifier allows anyone to call this function.
    *
    * @param _newNumber - The new value to store.
    */
    function setNumber(uint256 _newNumber) public {
        storedNumber = _newNumber;
    }
}

Compile the Smart Contract¶

To compile this contract, use the following script:

scripts/compile.js

const solc = require('solc');
const { readFileSync, writeFileSync, mkdirSync, existsSync } = require('fs');
const { basename, join } = require('path');

const ensureDir = (dirPath) => {
  if (!existsSync(dirPath)) {
    mkdirSync(dirPath, { recursive: true });
  }
};

const compileContract = (solidityFilePath, abiDir, artifactsDir) => {
  try {
    // Read the Solidity file
    const source = readFileSync(solidityFilePath, 'utf8');
    const fileName = basename(solidityFilePath);

    // Construct the input object for the Solidity compiler
    const input = {
      language: 'Solidity',
      sources: {
        [fileName]: {
          content: source,
        },
      },
      settings: {
        outputSelection: {
          '*': {
            '*': ['abi', 'evm.bytecode'],
          },
        },
      },
    };

    console.log(`Compiling contract: ${fileName}...`);

    // Compile the contract
    const output = JSON.parse(solc.compile(JSON.stringify(input)));

    // Check for errors
    if (output.errors) {
      const errors = output.errors.filter(error => error.severity === 'error');
      if (errors.length > 0) {
        console.error('Compilation errors:');
        errors.forEach(err => console.error(err.formattedMessage));
        return;
      }
      // Show warnings
      const warnings = output.errors.filter(error => error.severity === 'warning');
      warnings.forEach(warn => console.warn(warn.formattedMessage));
    }

    // Ensure output directories exist
    ensureDir(abiDir);
    ensureDir(artifactsDir);

    // Process compiled contracts
    for (const [sourceFile, contracts] of Object.entries(output.contracts)) {
      for (const [contractName, contract] of Object.entries(contracts)) {
        console.log(`Compiled contract: ${contractName}`);

        // Write the ABI
        const abiPath = join(abiDir, `${contractName}.json`);
        writeFileSync(abiPath, JSON.stringify(contract.abi, null, 2));
        console.log(`ABI saved to ${abiPath}`);

        // Write the bytecode
        const bytecodePath = join(artifactsDir, `${contractName}.bin`);
        writeFileSync(bytecodePath, contract.evm.bytecode.object);
        console.log(`Bytecode saved to ${bytecodePath}`);
      }
    }
  } catch (error) {
    console.error('Error compiling contracts:', error);
  }
};

const solidityFilePath = join(__dirname, '../contracts/Storage.sol');
const abiDir = join(__dirname, '../abis');
const artifactsDir = join(__dirname, '../artifacts');

compileContract(solidityFilePath, abiDir, artifactsDir);

Note

The script above is tailored to the Storage.sol contract. It can be adjusted for other contracts by changing the file name or modifying the ABI and bytecode paths.

The ABI (Application Binary Interface) is a JSON representation of your contract's functions, events, and their parameters. It serves as the interface between your JavaScript code and the deployed smart contract, allowing your application to know how to format function calls and interpret returned data.

Execute the script above by running:

node scripts/compile.js

After executing the script, the Solidity contract is compiled into standard EVM bytecode. The ABI and bytecode are saved into files with .json and .bin extensions, respectively. You can now proceed with deploying the contract to Polkadot Hub, as outlined in the next section.

Deploy the Compiled Contract¶

To deploy your compiled contract to Polkadot Hub, you'll need a wallet with a private key to sign the deployment transaction.

You can create a deploy.js script in the scripts directory of your project to achieve this. The deployment script can be divided into key components:

Set up the required imports and utilities:

scripts/deploy.js

const { writeFileSync, existsSync, readFileSync } = require('fs');
const { join } = require('path');
const { Web3 } = require('web3');

const scriptsDir = __dirname;
const abisDir = join(__dirname, '../abis');
const artifactsDir = join(__dirname, '../artifacts');

Create a provider to connect to Polkadot Hub:

scripts/deploy.js

const createProvider = (rpcUrl, chainId, chainName) => {
  const web3 = new Web3(rpcUrl);
  return web3;
};

Set up functions to read contract artifacts:

scripts/deploy.js

const getAbi = (contractName) => {
  try {
    const abiPath = join(abisDir, `${contractName}.json`);
    return JSON.parse(readFileSync(abiPath, 'utf8'));
  } catch (error) {
    console.error(
      `Could not find ABI for contract ${contractName}:`,
      error.message,
    );
    throw error;
  }
};

const getByteCode = (contractName) => {
  try {
    const bytecodePath = join(artifactsDir, `${contractName}.bin`);
    const bytecode = readFileSync(bytecodePath, 'utf8').trim();
    return bytecode.startsWith('0x') ? bytecode : `0x${bytecode}`;
  } catch (error) {
    console.error(
      `Could not find bytecode for contract ${contractName}:`,
      error.message,
    );
    throw error;
  }
};

Create the main deployment function:

scripts/deploy.js

const deployContract = async (contractName, privateKey, providerConfig) => {
  console.log(`Deploying ${contractName}...`);
  try {
    const web3 = createProvider(
      providerConfig.rpc,
      providerConfig.chainId,
      providerConfig.name,
    );

    const formattedPrivateKey = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
    const account = web3.eth.accounts.privateKeyToAccount(formattedPrivateKey);
    web3.eth.accounts.wallet.add(account);
    web3.eth.defaultAccount = account.address;

    const abi = getAbi(contractName);
    const bytecode = getByteCode(contractName);
    const contract = new web3.eth.Contract(abi);
    const deployTx = contract.deploy({
      data: bytecode,
    });

    const gas = await deployTx.estimateGas();
    const gasPrice = await web3.eth.getGasPrice();

    console.log(`Estimated gas: ${gas}`);
    console.log(`Gas price: ${web3.utils.fromWei(gasPrice, 'gwei')} gwei`);

    const deployedContract = await deployTx.send({
      from: account.address,
      gas: gas,
      gasPrice: gasPrice,
    });

    const address = deployedContract.options.address;
    console.log(`Contract ${contractName} deployed at: ${address}`);

    const addressesFile = join(scriptsDir, 'contract-address.json');
    const addresses = existsSync(addressesFile)
      ? JSON.parse(readFileSync(addressesFile, 'utf8'))
      : {};

    addresses[contractName] = address;
    writeFileSync(addressesFile, JSON.stringify(addresses, null, 2), 'utf8');
  } catch (error) {
    console.error(`Failed to deploy contract ${contractName}:`, error);
  }
};

Configure and execute the deployment:
scripts/deploy.js
```
const providerConfig = {
  rpc: 'https://services.polkadothub-rpc.com/testnet',
  chainId: 420420417,
  name: 'polkadotTestNet',
};

const privateKey = 'INSERT_PRIVATE_KEY';

deployContract('Storage', privateKey, providerConfig);
```
Note

A private key is a hexadecimal string that is used to sign and pay for the deployment transaction. Always keep your private key secure and never share it publicly.

Ensure to replace the INSERT_PRIVATE_KEY placeholder with your actual private key.

View complete script

scripts/deploy.js

const { writeFileSync, existsSync, readFileSync } = require('fs');
const { join } = require('path');
const { Web3 } = require('web3');

const scriptsDir = __dirname;
const abisDir = join(__dirname, '../abis');
const artifactsDir = join(__dirname, '../artifacts');

const createProvider = (rpcUrl, chainId, chainName) => {
  const web3 = new Web3(rpcUrl);
  return web3;
};

const getAbi = (contractName) => {
  try {
    const abiPath = join(abisDir, `${contractName}.json`);
    return JSON.parse(readFileSync(abiPath, 'utf8'));
  } catch (error) {
    console.error(
      `Could not find ABI for contract ${contractName}:`,
      error.message,
    );
    throw error;
  }
};

const getByteCode = (contractName) => {
  try {
    const bytecodePath = join(artifactsDir, `${contractName}.bin`);
    const bytecode = readFileSync(bytecodePath, 'utf8').trim();
    return bytecode.startsWith('0x') ? bytecode : `0x${bytecode}`;
  } catch (error) {
    console.error(
      `Could not find bytecode for contract ${contractName}:`,
      error.message,
    );
    throw error;
  }
};

const deployContract = async (contractName, privateKey, providerConfig) => {
  console.log(`Deploying ${contractName}...`);
  try {
    const web3 = createProvider(
      providerConfig.rpc,
      providerConfig.chainId,
      providerConfig.name,
    );

    const formattedPrivateKey = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
    const account = web3.eth.accounts.privateKeyToAccount(formattedPrivateKey);
    web3.eth.accounts.wallet.add(account);
    web3.eth.defaultAccount = account.address;

    const abi = getAbi(contractName);
    const bytecode = getByteCode(contractName);
    const contract = new web3.eth.Contract(abi);
    const deployTx = contract.deploy({
      data: bytecode,
    });

    const gas = await deployTx.estimateGas();
    const gasPrice = await web3.eth.getGasPrice();

    console.log(`Estimated gas: ${gas}`);
    console.log(`Gas price: ${web3.utils.fromWei(gasPrice, 'gwei')} gwei`);

    const deployedContract = await deployTx.send({
      from: account.address,
      gas: gas,
      gasPrice: gasPrice,
    });

    const address = deployedContract.options.address;
    console.log(`Contract ${contractName} deployed at: ${address}`);

    const addressesFile = join(scriptsDir, 'contract-address.json');
    const addresses = existsSync(addressesFile)
      ? JSON.parse(readFileSync(addressesFile, 'utf8'))
      : {};

    addresses[contractName] = address;
    writeFileSync(addressesFile, JSON.stringify(addresses, null, 2), 'utf8');
  } catch (error) {
    console.error(`Failed to deploy contract ${contractName}:`, error);
  }
};

const providerConfig = {
  rpc: 'https://services.polkadothub-rpc.com/testnet',
  chainId: 420420417,
  name: 'polkadotTestNet',
};

const privateKey = 'INSERT_PRIVATE_KEY';

deployContract('Storage', privateKey, providerConfig);

To run the script, execute the following command:

node scripts/deploy.js

After running this script, your contract will be deployed to Polkadot Hub, and its address will be saved in contract-address.json within your project directory. You can use this address for future contract interactions.

Interact with the Contract¶

Once the contract is deployed, you can interact with it by calling its functions. For example, to read the current stored value and then update it to a new value, you can create a file named updateStorage.js in the scripts directory of your project and add the following code:

scripts/updateStorage.js

const { readFileSync } = require('fs');
const { join } = require('path');
const { Web3 } = require('web3');

const abisDir = join(__dirname, '../abis');

const getAbi = (contractName) => {
  try {
    const abiPath = join(abisDir, `${contractName}.json`);
    return JSON.parse(readFileSync(abiPath, 'utf8'));
  } catch (error) {
    console.error(
      `Could not find ABI for contract ${contractName}:`,
      error.message,
    );
    throw error;
  }
};

const updateStorage = async (config) => {
  try {
    const web3 = new Web3(config.rpcUrl);
    const formattedPrivateKey = config.privateKey.startsWith('0x') ? config.privateKey : `0x${config.privateKey}`;
    const account = web3.eth.accounts.privateKeyToAccount(formattedPrivateKey);
    web3.eth.accounts.wallet.add(account);

    const abi = getAbi('Storage');
    const contract = new web3.eth.Contract(abi, config.contractAddress);

    const initialValue = await contract.methods.storedNumber().call();
    console.log('Current stored value:', initialValue);

    const updateTransaction = contract.methods.setNumber(1);
    const gasEstimate = await updateTransaction.estimateGas({
      from: account.address,
    });
    const gasPrice = await web3.eth.getGasPrice();

    const receipt = await updateTransaction.send({
      from: account.address,
      gas: gasEstimate,
      gasPrice: gasPrice,
    });

    console.log(`Transaction hash: ${receipt.transactionHash}`);

    const newValue = await contract.methods.storedNumber().call();
    console.log('New stored value:', newValue);

    return receipt;
  } catch (error) {
    console.error('Update failed:', error);
    throw error;
  }
};

const config = {
  rpcUrl: 'https://services.polkadothub-rpc.com/testnet',
  privateKey: 'INSERT_PRIVATE_KEY',
  contractAddress: 'INSERT_CONTRACT_ADDRESS',
};

updateStorage(config)
  .then((receipt) => console.log('Update successful'))
  .catch((error) => console.error('Update error'));

Ensure you replace the INSERT_PRIVATE_KEY and INSERT_CONTRACT_ADDRESS placeholders with actual values. Also, ensure the contract ABI file (Storage.json) is correctly referenced. The script reads the current stored value, sets it to 1, and then displays the updated value.

To interact with the contract, run:

node scripts/updateStorage.js

Where to Go Next¶

External Web3.js Docs

Explore the Web3.js documentation to learn how to use additional features, such as wallet management, signing messages, subscribing to events, and more.

Get Started

Last update: January 14, 2026
| Created: January 14, 2026