web3.js

web3.js is a Javascript library for building on EVM-compatible networks.

It allows developers to interact with smart contracts, send transactions, and retrieve data from the network.

Installation

info

This guide assumes you have the latest version of Node.js installed.

To install web3, run the following command:

npm install web3

Initialization

To use web3 in your project, start by importing the module and initializing your Web3 provider the desired Flow RPC endpoint.

const { Web3 } = require('web3')
const web3 = new Web3('https://previewnet.evm.nodes.onflow.org')

info

Currently, only Flow Previewnet is available. More networks are coming soon - see here for more info.

Querying the blockchain

web3 provides a number of methods for querying the blockchain, such as getting the latest block number, querying account balances, and more.

You can try using some of these methods to verify that your web3 instance is working correctly.

Getting the latest block number

const blockNumber = await web3.eth.getBlockNumber()
console.log(blockNumber) // Latest block number

Getting account balance

// Replace with the address of the account you want to query
const balance = await web3.eth.getBalance('0x1234')
console.log(balance) // Balance in attoFlow

Getting chain ID

const chainId = await web3.eth.getChainId()
console.log(chainId) // 0x286 (Flow Previewnet)

Getting gas price

const gasPrice = await web3.eth.getGasPrice()
console.log(gasPrice) // Gas price in attoFlow

For more information about what you can do with web3, please see the official documentation.

Interacting With Smart Contracts

The web3 library allows developers to interact with smart contracts via the web3.eth.Contract API.

For this example we will use the following "Storage" contract, deployed on the Flow Previewnet to the address 0x4c7784ae96e7cfcf0224a95059573e96f03a4e70. Note that anybody can interact with this contract, as it is deployed on a public network, so state may not always be as expected.

We recommend deploying your own contract, which can be done using Hardhat or Remix.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract Storage {
    uint256 public storedData;
    function store(uint256 x) public {
        storedData = x;
    }
    function retrieve() public view returns (uint256) {
        return storedData;
    }
}

The ABI for this contract can be generated using the solc compiler, or another tool such as Hardhat or Remix.

Now that we have both the ABI and address of the contract, we can create a new Contract object for use in our application.

// Replace with the ABI of the deployed contract
const abi = [
    {
        "inputs": [],
        "stateMutability": "nonpayable",
        "type": "constructor"
    },
    {
        "inputs": [
            {
                "internalType": "uint256",
                "name": "x",
                "type": "uint256"
            }
        ],
        "name": "store",
        "outputs": [],
        "stateMutability": "nonpayable",
        "type": "function"
    },
    {
        "inputs": [],
        "name": "retrieve",
        "outputs": [
            {
                "internalType": "uint256",
                "name": "",
                "type": "uint256"
            }
        ],
        "stateMutability": "view",
        "type": "function"
    }
]
// Replace with the address of the deployed contract
const contractAddress = "0x4c7784ae96e7cfcf0224a95059573e96f03a4e70"
// Create a new contract object with the ABI and address
const contract = new web3.eth.Contract(abi, contractAddress)

Using this newly created object, we can now interact with the contract on the network.

Reading State

Querying data from the contract is done using the call function with one of the contract's methods. This will not change the state and will not send a transaction.

// Retrieve the current value stored in the contract
// (this is using the `retrieve` method from the contract with no arguments)
const result = await contract.methods.retrieve().call()
console.log(result) // Current value stored in the contract

Changing State

We can mutate the state of the contract by sending a transaction to the network.

In order to send a transaction to the network, you will need an account with sufficient funds to pay for the transaction.

info

If you do not have an account yet, you can create one using the following command from your project's root directory:

node -e "console.log(require('web3').eth.accounts.create())"

For Flow Previewnet, you can fund your account using the Flow Faucet.

First, we will need to be able to sign a transaction using an account. To do this, we can use the privateKeyToAccount function to create an Web3Account object from the account's private key.

// You must replace this with the private key of the account you wish to use
const account = web3.eth.accounts.privateKeyToAccount('0x1234')

Then, we can sign a transaction using the user's account and send it to the network.

const newValue = 1337 // Replace with any value you want to store
// Sign a transaction that stores a new value in the contract
// (this is using the `store` method from the contract with the new value as an argument)
let signed = await account.signTransaction({
    from: account.address,
    to: contractAddress,
    data: contract.methods.store(newValue).encodeABI(),
    gas: 10000000n, // Replace with the gas limit you want to use
    gasPrice: await web3.eth.getGasPrice(), // Replace with the gas price you want to use
})
// Send signed transaction to the network
const result = await web3.eth.sendSignedTransaction(signed.rawTransaction)
// { status: 1, transactionHash: '0x1234', ... }
// status=1 means the transaction was successful
console.log(result)

Now that the transaction has been sent, the contract's state has been updated. We an verify this by querying the contract's state again.

const result = await contract.methods.retrieve().call()
console.log(result) // new value stored in the contract

For more information about using smart contracts in web3.js, see the official documentation.

web3.js

Installation​

Initialization​

Querying the blockchain​

Getting the latest block number​

Getting account balance​

Getting chain ID​

Getting gas price​

Interacting With Smart Contracts​

Reading State​

Changing State​

Installation

Initialization

Querying the blockchain

Getting the latest block number

Getting account balance

Getting chain ID

Getting gas price

Interacting With Smart Contracts

Reading State

Changing State