Deploying and interacting with smart contracts

Unlike most software, smart contracts don’t run on your computer or somebody’s server: they live on the Ethereum network itself. This means that interacting with them is a bit different from more traditional applications.

This guide will cover all you need to know to get you started using your contracts, including:

Instructions are available for both Truffle and Hardhat. Choose your preference using this toggle!

Setting up a Local Blockchain

Before we begin, we first need an environment where we can deploy our contracts. The Ethereum blockchain (often called "mainnet", for "main network") requires spending real money to use it, in the form of Ether (its native currency). This makes it a poor choice when trying out new ideas or tools.

To solve this, a number of "testnets" (for "test networks") exist: these include the Sepolia, and Goerli blockchains. They work very similarly to mainnet, with one difference: you can get Ether for these networks for free, so that using them doesn’t cost you a single cent. However, you will still need to deal with private key management, blocktimes in the range of 5 to 20 seconds, and actually getting this free Ether.

During development, it is a better idea to instead use a local blockchain. It runs on your machine, requires no Internet access, provides you with all the Ether that you need, and mines blocks instantly. These reasons also make local blockchains a great fit for automated tests.

If you want to learn how to deploy and use contracts on a public blockchain, like the Ethereum testnets, head to our Connecting to Public Test Networks guide.

The most popular local blockchain is Ganache. To install it on your project, run:

$ npm install --save-dev ganache-cli

Upon startup, Ganache will create a random set of unlocked accounts and give them Ether. In order to get the same addresses that will be used in this guide, you can start Ganache in deterministic mode:

$ npx ganache-cli --deterministic

Ganache will print out a list of available accounts and their private keys, along with some blockchain configuration values. Most importantly, it will display its address, which we’ll use to connect to it. By default, this will be 127.0.0.1:8545.

Keep in mind that every time you run Ganache, it will create a brand new local blockchain - the state of previous runs is not preserved. This is fine for short-lived experiments, but it means that you will need to have a window open running Ganache for the duration of these guides. Alternatively, you can run Ganache with the --db option, providing a directory to store its data in between runs.

Truffle has a graphical version of ganache-cli, also called Ganache.

Hardhat comes with a local blockchain built-in, the Hardhat Network.

Upon startup, Hardhat Network will create a set of unlocked accounts and give them Ether.

$ npx hardhat node

Hardhat Network will print out its address, http://127.0.0.1:8545, along with a list of available accounts and their private keys.

Keep in mind that every time you run Hardhat Network, it will create a brand new local blockchain - the state of previous runs is not preserved. This is fine for short-lived experiments, but it means that you will need to have a window open running Hardhat Network for the duration of these guides.

Hardhat will always spin up an instance of Hardhat Network when no network is specified and there is no default network configured or the default network is set to hardhat.
You can also run an actual Ethereum node in development mode. These are a bit more complex to set up, and not as flexible for testing and development, but are more representative of the real network.

Deploying a Smart Contract

In the Developing Smart Contracts guide we set up our development environment.

If you don’t already have this setup, please create and setup the project and then create and compile our Box smart contract.

With our project setup complete we’re now ready to deploy a contract. We’ll be deploying Box, from the Developing Smart Contracts guide. Make sure you have a copy of Box in contracts/Box.sol.

Truffle uses migrations to deploy contracts. Migrations consist of JavaScript files and a special Migrations contract to track migrations on-chain.

We will create a JavaScript migration to deploy our Box contract. We will save this file as migrations/2_deploy.js.

// migrations/2_deploy.js
const Box = artifacts.require('Box');

module.exports = async function (deployer) {
  await deployer.deploy(Box);
};

Hardhat doesn’t currently have a native deployment system, instead we use scripts to deploy contracts.

We will create a script to deploy our Box contract. We will save this file as scripts/deploy.js.

// scripts/deploy.js
async function main () {
  // We get the contract to deploy
  const Box = await ethers.getContractFactory('Box');
  console.log('Deploying Box...');
  const box = await Box.deploy();
  await box.deployed();
  console.log('Box deployed to:', box.address);
}

main()
  .then(() => process.exit(0))
  .catch(error => {
    console.error(error);
    process.exit(1);
  });

We use ethers in our script, so we need to install it and the @nomicfoundation/hardhat-ethers plugin.

$ npm install --save-dev @nomicfoundation/hardhat-ethers ethers

Before we deploy we need to configure the connection to ganache. We need to add a development network for localhost and port 8545 which is what our local blockchain is using.

// truffle-config.js
module.exports = {
...
  networks: {
...
    development: {
     host: "127.0.0.1",     // Localhost (default: none)
     port: 8545,            // Standard Ethereum port (default: none)
     network_id: "*",       // Any network (default: none)
    },
    ...

We need to add in our configuration that we are using the @nomiclabs/hardhat-ethers plugin.

// hardhat.config.js
require("@nomicfoundation/hardhat-ethers");

...
module.exports = {
...
};

Using the migrate command, we can deploy the Box contract to the development network (Ganache):

$ npx truffle migrate --network development

Compiling your contracts...
===========================
> Everything is up to date, there is nothing to compile.



Starting migrations...
======================
> Network name:    'development'
> Network id:      1619762548805
> Block gas limit: 6721975 (0x6691b7)


1_initial_migration.js
======================

   Deploying 'Migrations'
   ----------------------
...

2_deploy.js
===========

   Deploying 'Box'
   ---------------
   > transaction hash:    0x25b0a326bfc9aa64be13efb5a4fb3f784ffa845c36d049547eeb0f78e0a3108d
   > Blocks: 0            Seconds: 0
   > contract address:    0xCfEB869F69431e42cdB54A4F4f105C19C080A601
...
Truffle will keep track of your deployed contracts, but it also displays their addresses when deploying (in our example, 0xCfEB869F69431e42cdB54A4F4f105C19C080A601). These values will be useful when interacting with them programmatically.

Using the run command, we can deploy the Box contract to the local network (Hardhat Network):

$ npx hardhat run --network localhost scripts/deploy.js
Deploying Box...
Box deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
Hardhat doesn’t keep track of your deployed contracts. We displayed the deployed address in our script (in our example, 0x5FbDB2315678afecb367f032d93F642f64180aa3). This will be useful when interacting with them programmatically.

All done! On a real network this process would’ve taken a couple of seconds, but it is near instant on local blockchains.

If you got a connection error, make sure you are running a local blockchain in another terminal.
Remember that local blockchains do not persist their state throughout multiple runs! If you close your local blockchain process, you’ll have to re-deploy your contracts.

Interacting from the Console

With our Box contract deployed, we can start using it right away.

We will use the Truffle console to interact with our deployed Box contract on our local development network.

$ npx truffle console --network development
truffle(development)> const box = await Box.deployed();
undefined

We will use the Hardhat console to interact with our deployed Box contract on our localhost network.

We need to specify the address of our Box contract we displayed in our deploy script.
It’s important that we explicitly set the network for Hardhat to connect our console session to. If we don’t, Hardhat will default to using a new ephemeral network, which our Box contract wouldn’t be deployed to. 
$ npx hardhat console --network localhost
Welcome to Node.js v12.22.1.
Type ".help" for more information.
> const Box = await ethers.getContractFactory('Box');
undefined
> const box = await Box.attach('0x5FbDB2315678afecb367f032d93F642f64180aa3')
undefined

Sending transactions

Box's first function, store, receives an integer value and stores it in the contract storage. Because this function modifies the blockchain state, we need to send a transaction to the contract to execute it.

We will send a transaction to call the store function with a numeric value:

truffle(development)> await box.store(42)
{ tx:
   '0x5d4cc78f5d5eac3650214740728192ac760978e261962736289b10da0ec0ea43',
...
       event: 'ValueChanged',
       args: [Result] } ] }

Notice how the transaction receipt also shows that Box emitted a ValueChanged event.

> await box.store(42)
{
  hash: '0x3d86c5c2c8a9f31bedb5859efa22d2d39a5ea049255628727207bc2856cce0d3',
...

Querying state

Box's other function is called retrieve, and it returns the integer value stored in the contract. This is a query of blockchain state, so we don’t need to send a transaction:

truffle(development)> await box.retrieve()
<BN: 2a>
> await box.retrieve()
BigNumber { _hex: '0x2a', _isBigNumber: true }

Because queries only read state and don’t send a transaction, there is no transaction hash to report. This also means that using queries doesn’t cost any Ether, and can be used for free on any network.

Our Box contract returns uint256 which is too large a number for JavaScript so instead we get returned a big number object. We can display the big number as a string using (await box.retrieve()).toString(). 
truffle(development)> (await box.retrieve()).toString()
'42'
> (await box.retrieve()).toString()
'42'
To learn more about using the console, check out the Truffle documentation.
To learn more about using the console, check out the Hardhat documentation.

Interacting programmatically

The console is useful for prototyping and running one-off queries or transactions. However, eventually you will want to interact with your contracts from your own code.

In this section, we’ll see how to interact with our contracts from JavaScript, and use Truffle to execute our script with our Truffle configuration.

In this section, we’ll see how to interact with our contracts from JavaScript, and use Hardhat to run our script with our Hardhat configuration.

Keep in mind that there are many other JavaScript libraries available, and you can use whichever you like the most. Once a contract is deployed, you can interact with it through any library!

Setup

Let’s start coding in a new scripts/index.js file, where we’ll be writing our JavaScript code, beginning with some boilerplate, including for writing async code.

// scripts/index.js
module.exports = async function main (callback) {
  try {
    // Our code will go here

    callback(0);
  } catch (error) {
    console.error(error);
    callback(1);
  }
};
// scripts/index.js
async function main () {
  // Our code will go here
}

main()
  .then(() => process.exit(0))
  .catch(error => {
    console.error(error);
    process.exit(1);
  });

We can test our setup by asking the local node something, such as the list of enabled accounts:

// Retrieve accounts from the local node
const accounts = await web3.eth.getAccounts();
console.log(accounts)
// Retrieve accounts from the local node
const accounts = await ethers.provider.listAccounts();
console.log(accounts);
We won’t be repeating the boilerplate code on every snippet, but make sure to always code inside the main function we defined above!

Run the code above using truffle exec, and check that you are getting a list of available accounts in response.

$ npx truffle exec --network development ./scripts/index.js
Using network 'development'.

[ '0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1',
  '0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0',
...
]

Run the code above using hardhat run, and check that you are getting a list of available accounts in response.

$ npx hardhat run --network localhost ./scripts/index.js
[
  '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
  '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
...
]

These accounts should match the ones displayed when you started the local blockchain earlier. Now that we have our first code snippet for getting data out of a blockchain, let’s start working with our contract. Remember we are adding our code inside the main function we defined above.

Getting a contract instance

In order to interact with the Box contract we deployed, we’ll use the Truffle contract abstraction, a JavaScript object that represents our contract on the blockchain.

// Set up a Truffle contract, representing our deployed Box instance
const Box = artifacts.require('Box');
const box = await Box.deployed();

In order to interact with the Box contract we deployed, we’ll use an ethers contract instance.

An ethers contract instance is a JavaScript object that represents our contract on the blockchain, which we can use to interact with our contract. To attach it to our deployed contract we need to provide the contract address.

// Set up an ethers contract, representing our deployed Box instance
const address = '0x5FbDB2315678afecb367f032d93F642f64180aa3';
const Box = await ethers.getContractFactory('Box');
const box = await Box.attach(address);
Make sure to replace the address with the one you got when deploying the contract, which may be different to the one shown here.

We can now use this JavaScript object to interact with our contract.

Calling the contract

Let’s start by displaying the current value of the Box contract.

We’ll need to call the retrieve() public method of the contract, and await the response:

// Call the retrieve() function of the deployed Box contract
const value = await box.retrieve();
console.log('Box value is', value.toString());

We’ll need to call the read only retrieve() public method of the contract, and await the response:

// Call the retrieve() function of the deployed Box contract
const value = await box.retrieve();
console.log('Box value is', value.toString());

This snippet is equivalent to the query we ran earlier from the console. Now, make sure everything is running smoothly by running the script again and checking the printed value:

$ npx truffle exec --network development ./scripts/index.js
Using network 'development'.

Box value is 42
$ npx hardhat run --network localhost ./scripts/index.js
Box value is 42

If you restarted your local blockchain at any point, this script may fail. Restarting clears all local blockchain state, so the Box contract instance won’t be at the expected address.

If this happens, simply start the local blockchain and redeploy the Box contract.

Sending a transaction

We’ll now send a transaction to store a new value in our Box.

Let’s store a value of 23 in our Box, and then use the code we had written before to display the updated value:

// Send a transaction to store() a new value in the Box
await box.store(23);

// Call the retrieve() function of the deployed Box contract
const value = await box.retrieve();
console.log('Box value is', value.toString());
In a real-world application, you may want to estimate the gas of your transactions, and check a gas price oracle to know the optimal values to use on every transaction. 
// Send a transaction to store() a new value in the Box
await box.store(23);

// Call the retrieve() function of the deployed Box contract
const value = await box.retrieve();
console.log('Box value is', value.toString());
In a real-world application, you may want to estimate the gas of your transactions, and check a gas price oracle to know the optimal values to use on every transaction.

We can now run the snippet, and check that the box’s value is updated!

$ npx truffle exec --network development ./scripts/index.js
Using network 'development'.

Box value is 23
$ npx hardhat run --network localhost ./scripts/index.js
Box value is 23

Next steps

Now that you know how to set up a local blockchain, deploy contracts and interact with them both manually and programmatically, you will need to learn about testing environments, public test networks and going to production:

← Developing smart contracts
Writing automated tests →