Ethers.js
About
The Ethers.js library provides a set of tools to interact with Ethereum Nodes with JavaScript, similar to Web3.js. Moonbeam has an Ethereum-like API available that is fully compatible with Ethereum-style JSON-RPC invocations. Therefore, developers can leverage this compatibility and use the Ethers.js library to interact with a Moonbeam node as if they were doing so on Ethereum. For more information on Ethers.js, check their documentation site.
In this guide, you'll learn how to use the Ethers.js library to send a transaction and deploy a contract on Viction.
Checking Prerequisites
To test out the examples in this guide on Viction mainnet or testnet, you will need to have the corresponding RPC API endpoints and some native VIC tokens.
The examples in this guide assumes you have a MacOS or Ubuntu 18.04-based environment and will need to be adapted accordingly for Windows.
Installing Ethers.js
To get started, you'll need to start a basic JavaScript project. First, create a directory to store all of the files you'll be creating throughout this guide and initialize the project with the following command:
For this guide, you'll need to install the Ethers.js library and the Solidity compiler. To install both NPM packages, you can run the following command:
npm install ethers solc@0.8.0
Setting up the Ethers Provider
Throughout this guide, you'll be creating a bunch of scripts that provide different functionality such as sending a transaction, deploying a contract, and interacting with a deployed contract. In most of these scripts you'll need to create an Ethers provider to interact with the network.
To create a provider, you can take the following steps:
Import the
ethers
library.Define the
providerRPC
object, which can include the network configurations for any of the networks you want to send a transaction on. You'll include thename
,rpc
, andchainId
for each network.Create the
provider
using theethers.JsonRpcProvider
method.
Save this code snippet as you'll need it for the scripts that are used in the following sections.
Send a Transaction
During this section, you'll be creating a couple of scripts. The first one will be to check the balances of your accounts before trying to send a transaction. The second script will actually send the transaction.
You can also use the balance script to check the account balances after the transaction has been sent.
Check Balances Script
You'll only need one file to check the balances of both addresses before and after the transaction is sent. To get started, you can create a balances.js
file by running:
Next, you will create the script for this file and complete the following steps:
Define the
addressFrom
andaddressTo
variables.Create the asynchronous
balances
function which wraps theprovider.getBalance
method.Use the
provider.getBalance
function to fetch the balances for theaddressFrom
andaddressTo
addresses. You can also leverage theethers.formatEther
function to transform the balance into a more readable number in VIC.Lastly, run the
balances
function.
To run the script and fetch the account balances, you can run the following command:
If successful, the balances for the origin and receiving address will be displayed in your terminal.
Send Transaction Script
You'll only need one file for executing a transaction between accounts. For this example, you'll be transferring 1 VIC token from an origin address (from which you hold the private key) to another address. To get started, you can create a transaction.js
file by running:
Next, you will create the script for this file and complete the following steps:
Define the
privateKey
and theaddressTo
variables. The private key is required to create a wallet instance. Note: This is for example purposes only. Never store your private keys in a JavaScript file.Create a wallet using the
privateKey
andprovider
from the previous steps. The wallet instance is used to sign transactions.Create the asynchronous
send
function which wraps the transaction object and thewallet.sendTransaction
method.Create the transaction object which only requires the recipient's address and the amount to send. Note that
ethers.parseEther
can be used, which handles the necessary unit conversions from Ether to Wei - similar to usingethers.parseUnits(value, 'ether')
.Send the transaction using the
wallet.sendTransaction
method and then useawait
to wait until the transaction is processed and the transaction receipt is returned.Lastly, run the
send
function.
To run the script, you can run the following command in your terminal:
If the transaction was succesful, in your terminal you'll see the transaction hash has been printed out.
You can also use the balances.js
script to check that the balances for the origin and receiving accounts have changed.
Deploy a Contract
The contract you'll be compiling and deploying in the next couple of sections is a simple incrementer contract, arbitrarily named Incrementer.sol
. You can get started by creating a file for the contract:
Next, you can add the Solidity code to the file:
The constructor
function, which runs when the contract is deployed, sets the initial value of the number variable stored on-chain (the default is 0
). The increment
function adds the _value
provided to the current number, but a transaction needs to be sent, which modifies the stored data. Lastly, the reset
function resets the stored value to zero.
This contract is a simple example for illustration purposes only and does not handle values wrapping around.
Compile Contract Script
In this section, you'll create a script that uses the Solidity compiler to output the bytecode and interface (ABI) for the Incrementer.sol
contract. To get started, you can create a compile.js
file by running:
Next, you will create the script for this file and complete the following steps:
Import the
fs
andsolc
packages.Using the
fs.readFileSync
function, you'll read and save the file contents ofIncrementer.sol
tosource
.Build the
input
object for the Solidity compiler by specifying thelanguage
,sources
, andsettings
to be used.Using the
input
object, you can compile the contract usingsolc.compile
.Extract the compiled contract file and export it to be used in the deployment script.
Deploy Contract Script
With the script for compiling the Incrementer.sol
contract in place, you can then use the results to send a signed transaction that deploys it. To do so, you can create a file for the deployment script called deploy.js
:
Next, you will create the script for this file and complete the following steps:
Import the contract file from
compile.js
.Define the
privateKey
for the origin account. The private key is required to create a wallet instance. Note: This is for example purposes only. Never store your private keys in a JavaScript file.Create a wallet using the
privateKey
andprovider
from the previous steps. The wallet instance is used to sign transactions.Load the contract
bytecode
andabi
for the compiled contract.Create a contract instance with signer using the
ethers.ContractFactory
function, providing theabi
,bytecode
, andwallet
as parameters.Create the asynchronous
deploy
function that will be used to deploy the contract.Within the
deploy
function, use theincrementer
contract instance to calldeploy
and pass in the initial value. For this example, you can set the initial value to5
. This will send the transaction for contract deployment. To wait for a transaction receipt you can use thedeployed
method of the contract deployment transaction.Lastly, run the
deploy
function.
To run the script, you can enter the following command into your terminal:
If successful, the contract's address will be displayed in the terminal.
Read Contract Data (Call Methods)
Call methods are the type of interaction that don't modify the contract's storage (change variables), meaning no transaction needs to be sent. They simply read various storage variables of the deployed contract.
To get started, you can create a file and name it get.js
:
Then you can take the following steps to create the script:
Import the
abi
from thecompile.js
file.Create the
contractAddress
variable using the address of the deployed contract.Create an instance of the contract using the
ethers.Contract
function and passing in thecontractAddress
,abi
, andprovider
.Create the asynchronous
get
function.Use the contract instance to call one of the contract's methods and pass in any inputs if necessary. For this example, you will call the
number
method which doesn't require any inputs. You can useawait
which will return the value requested once the request promise resolves.Lastly, call the
get
function.
To run the script, you can enter the following command in your terminal:
If successful, the value will be displayed in the terminal.
Interact with Contract (Send Methods)
Send methods are the type of interaction that modify the contract's storage (change variables), meaning a transaction needs to be signed and sent. In this section, you'll create two scripts: one to increment and one to reset the incrementer. To get started, you can create a file for each script and name them increment.js
and reset.js
:
Open the increment.js
file and take the following steps to create the script:
Import the
abi
from thecompile.js
file.Define the
privateKey
for the origin account, thecontractAddress
of the deployed contract, and the_value
to increment by. The private key is required to create a wallet instance. Note: This is for example purposes only. Never store your private keys in a JavaScript file.Create a wallet using the
privateKey
andprovider
from the previous steps. The wallet instance is used to sign transactions.Create an instance of the contract using the
ethers.Contract
function and passing in thecontractAddress
,abi
, andprovider
.Create the asynchronous
increment
function.Use the contract instance to call one of the contract's methods and pass in any inputs if necessary. For this example, you will call the
increment
method which requires the value to increment by as an input. You can useawait
which will return the value requested once the request promise resolves.Lastly, call the
increment
function.
To run the script, you can enter the following command in your terminal:
If successful, the transaction hash will be displayed in the terminal. You can use the get.js
script alongside the increment.js
script. Next you can open the reset.js
file and take the following steps to create the script:
Import the
abi
from thecompile.js
file.Define the
privateKey
for the origin account and thecontractAddress
of the deployed contract. The private key is required to create a wallet instance. Note: This is for example purposes only. Never store your private keys in a JavaScript file.Create a wallet using the
privateKey
andprovider
from the previous steps. The wallet instance is used to sign transactions.Create an instance of the contract using the
ethers.Contract
function and passing in thecontractAddress
,abi
, andprovider
.Create the asynchronous
reset
function.Use the contract instance to call one of the contract's methods and pass in any inputs if necessary. For this example, you will call the
reset
method which doesn't require any inputs. You can useawait
which will return the value requested once the request promise resolves.Lastly, call the
reset
function.
To run the script, you can enter the following command in your terminal:
If successful, the transaction hash will be displayed in the terminal. You can use the get.js
script alongside the reset.js
script to make sure that value is changing as expected.
Last updated