Sei EVM Development with Hardhat

Learn how to set up Hardhat for Sei EVM development, create and deploy smart contracts, and leverage OpenZeppelin components for secure, standardized implementations.

This tutorial shows how to set up Hardhat for Sei EVM development. It covers environment setup, contract creation, and deployment. You use OpenZeppelin’s pre-built components to build secure, standardized smart contracts.

Watch the video walkthrough for this topic in the Video Tutorials section.

Deploy to Sei Testnet first

We highly recommend that you deploy to Sei Testnet first. Make sure that everything works as expected before you deploy to Sei Mainnet. This helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe.

Try it before you install

The full toolchain takes a few minutes to set up. If you only want to see a contract deploy to Sei, you can do both of these steps in the browser now.

First, confirm that the RPC endpoints you will use in hardhat.config respond:

Then add Sei Testnet to your wallet and deploy a minimal Counter.sol from Remix. You do not need Node.js or a local install. In Remix, compile the contract under Solidity Compiler. Then deploy it under Deploy & Run, with Environment set to Injected Provider - MetaMask.

Table of contents

• Try it before you install
• Prerequisites
• Setting up your development environment
• Configuring Hardhat for Sei EVM
• Using OpenZeppelin contracts
• Creating and deploying an ERC20 token, ERC721 NFT or an upgradeable UUPS token
• Testing your smart contracts
• Deploying to Sei Testnet and Mainnet

Prerequisites

Before you start, make sure that you have installed these tools:

• Node.js (v18.0.0 or later)
• npm (v7.0.0 or later) or yarn
• A code editor (VS Code recommended)

Setting up your development environment

Create a new project and set up Hardhat:

# Create a new directory for your project
mkdir sei-hardhat-project
cd sei-hardhat-project

# Scaffold a Hardhat 3 project (ESM + TypeScript)
npx hardhat --init

When prompted, choose Hardhat 3 and a TypeScript project using Mocha and Ethers.js. Then follow the prompts. This generates an ESM project ("type": "module" in package.json) with @nomicfoundation/hardhat-toolbox-mocha-ethers, ethers, Hardhat Ignition, TypeScript, and a ready-to-use tsconfig.json.

Then add the OpenZeppelin contract library:

npm install @openzeppelin/contracts

For a non-interactive setup (CI or scripted environments), do the same steps manually, without prompts:

npm init -y
npm pkg set type=module
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox-mocha-ethers @openzeppelin/contracts typescript @types/node

The @nomicfoundation/hardhat-toolbox-mocha-ethers bundle includes ethers, Ignition, Mocha and Chai, and the keystore, network-helpers, verify, and typechain plugins. This single install covers everything in this guide. If you get peer-dependency errors, run the install again with --legacy-peer-deps.

Configuring Hardhat for Sei EVM

Next, configure Hardhat to work with the Sei EVM. Update your hardhat.config.ts file:

hardhat.config.ts

import type { HardhatUserConfig } from 'hardhat/config';
import { configVariable } from 'hardhat/config';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';

const config: HardhatUserConfig = {
  // Hardhat 3 loads plugins from an explicit array — no side-effect `import` statements
  plugins: [hardhatToolboxMochaEthers],
  solidity: {
    version: '0.8.28',
    settings: {
      optimizer: {
        enabled: true,
        runs: 200
      }
    }
  },
  networks: {
    // Sei Testnet
    seitestnet: {
      type: 'http',
      chainType: 'l1',
      url: 'https://evm-rpc-testnet.sei-apis.com',
      accounts: [configVariable('SEI_PRIVATE_KEY')],
      chainId: 1328
    },
    // Sei Mainnet
    seimainnet: {
      type: 'http',
      chainType: 'l1',
      url: 'https://evm-rpc.sei-apis.com',
      accounts: [configVariable('SEI_PRIVATE_KEY')],
      chainId: 1329
    }
  }
};

export default config;

Hardhat 3 is ESM-first and requires "type": "module" in package.json. The scaffold sets this for you. Each network needs an explicit type: 'http'. Plugins load through the plugins array, not through the Hardhat 2 side-effect import '@nomicfoundation/hardhat-toolbox'. A local simulated network is available automatically, so you do not need a hardhat or localhost entry.

Hardhat 3 reads secrets through configVariable(...), which reads from an encrypted keystore. Hardhat never stores your key in a plaintext file. Set the key once:

npx hardhat keystore set SEI_PRIVATE_KEY

Hardhat prompts you to paste the private key of the account that you deploy from. It stores the key encrypted on your machine. For CI, export a SEI_PRIVATE_KEY environment variable instead. configVariable falls back to this variable.

Use a dedicated, throwaway deploy key that holds only the funds you need. Never use a personal wallet that holds real funds.

Using OpenZeppelin contracts

OpenZeppelin has a library of secure, tested smart contract components that you can use to build your dApps. You installed the @openzeppelin/contracts package during setup, so you can import its contracts directly.

Creating and deploying an ERC20 token, ERC721 NFT or an upgradeable UUPS token

ERC20

To create a simple ERC20 token with OpenZeppelin contracts, add a new file named SeiToken.sol to the contracts directory:

contracts/SeiToken.sol

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

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract SeiToken is ERC20, Ownable {
    constructor(address initialOwner)
        ERC20("Sei Token", "SEI")
        Ownable(initialOwner)
    {
        // Mint 1 million tokens to the contract deployer (with 18 decimals)
        _mint(msg.sender, 1000000 * 10 ** decimals());
    }

    // Function to mint new tokens (only owner)
    function mint(address to, uint256 amount) public onlyOwner {
        _mint(to, amount);
    }

    // Function to burn tokens
    function burn(uint256 amount) public {
        _burn(msg.sender, amount);
    }
}

Next, create a deployment script named deploy-sei-token.ts in the ignition/modules directory:

ignition/modules/deploy-sei-token.ts

import { buildModule } from '@nomicfoundation/hardhat-ignition/modules';

export default buildModule('SeiTokenModule', (m) => {
  const deployer = m.getAccount(0);

  const seiToken = m.contract('SeiToken', [deployer]);

  return { seiToken };
});

To deploy the token to Sei Testnet, run this command:

npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seitestnet

ERC721

To create an ERC721 NFT contract, add a new file named SeiNFT.sol to the contracts directory:

contracts/SeiNFT.sol

// SPDX-License-Identifier: MIT
// Compatible with OpenZeppelin Contracts ^5.0.0
pragma solidity ^0.8.22;

import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import {ERC721Burnable} from "@openzeppelin/contracts/token/ERC721/extensions/ERC721Burnable.sol";
import {ERC721Enumerable} from "@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol";
import {ERC721Pausable} from "@openzeppelin/contracts/token/ERC721/extensions/ERC721Pausable.sol";
import {ERC721URIStorage} from "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

contract SeiNFT is ERC721, ERC721Enumerable, ERC721URIStorage, ERC721Pausable, Ownable, ERC721Burnable {
    uint256 private _nextTokenId;

     // Base URI for metadata
    string private _baseTokenURI;

    constructor(address initialOwner, string memory baseTokenURI)
        ERC721("Sei NFT Collection", "SEINFT")
        Ownable(initialOwner)
    {
        _baseTokenURI = baseTokenURI;
    }

    // Function to update the base URI (only owner)
    function setBaseURI(string memory baseTokenURI) public onlyOwner {
        _baseTokenURI = baseTokenURI;
    }

    // Override the baseURI function
    function _baseURI() internal view override returns (string memory) {
        return _baseTokenURI;
    }

    function pause() public onlyOwner {
        _pause();
    }

    function unpause() public onlyOwner {
        _unpause();
    }

    function safeMint(address to, string memory uri)
        public
        onlyOwner
        returns (uint256)
    {
        uint256 tokenId = _nextTokenId++;
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
        return tokenId;
    }

    // The following functions are overrides required by Solidity.

    function _update(address to, uint256 tokenId, address auth)
        internal
        override(ERC721, ERC721Enumerable, ERC721Pausable)
        returns (address)
    {
        return super._update(to, tokenId, auth);
    }

    function _increaseBalance(address account, uint128 value)
        internal
        override(ERC721, ERC721Enumerable)
    {
        super._increaseBalance(account, value);
    }

    function tokenURI(uint256 tokenId)
        public
        view
        override(ERC721, ERC721URIStorage)
        returns (string memory)
    {
        return super.tokenURI(tokenId);
    }

    function supportsInterface(bytes4 interfaceId)
        public
        view
        override(ERC721, ERC721Enumerable, ERC721URIStorage)
        returns (bool)
    {
        return super.supportsInterface(interfaceId);
    }
}

Create a deployment script named deploy-sei-nft.ts:

scripts/deploy-sei-nft.ts

import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

const [deployer] = await ethers.getSigners();
console.log('Deploying contracts with the account:', deployer.address);

// Base URI for your NFT metadata
const baseURI = 'https://your-metadata-server.com/metadata/';

const SeiNFT = await ethers.getContractFactory('SeiNFT');
const seiNFT = await SeiNFT.deploy(deployer.address, baseURI);
await seiNFT.waitForDeployment();

console.log('SeiNFT deployed to:', await seiNFT.getAddress());

// Mint an example NFT
console.log('Minting an example NFT...');
const mintTx = await seiNFT.safeMint(deployer.address, '0.json');
const receipt = await mintTx.wait();
// _nextTokenId starts at 0, so the first minted token has ID 0.
// Read the actual ID from the Transfer event:
const transferEvent = receipt.logs.map((log) => seiNFT.interface.parseLog(log)).find((parsed) => parsed?.name === 'Transfer');
console.log('NFT minted with ID:', transferEvent?.args.tokenId.toString() ?? 'unknown (no Transfer event in receipt)');

Deploy the NFT contract to Sei Testnet:

npx hardhat run scripts/deploy-sei-nft.ts --network seitestnet

Upgradeable UUPS Token

With an upgradeable contract, you can change the contract’s logic after deployment without changing the contract address. You can use this to fix bugs or add new features. The UUPS (Universal Upgradeable Proxy Standard) pattern is a popular way to implement upgradeability.

The @openzeppelin/contracts package that you installed earlier includes the ERC1967 proxy. For upgradeable contracts, also install the upgradeable variant of the OpenZeppelin library:

npm install @openzeppelin/contracts-upgradeable

OpenZeppelin’s @openzeppelin/hardhat-upgrades plugin is built for Hardhat 2 and does not register with Hardhat 3’s plugins array. For this reason, this guide deploys the proxy directly with the ERC1967 standard and upgrades it through the UUPS upgradeToAndCall function. This method needs no extra plugin and is fully native to Hardhat 3. The tradeoff is that you do not get the plugin’s automatic storage-layout safety checks. Make sure that each new version only appends state variables. You can validate layouts separately with @openzeppelin/upgrades-core.

You do not need to change hardhat.config.ts beyond the configuration shown earlier.

Next, create the upgradeable ERC20 token in contracts/UpgradeableSeiToken.sol:

contracts/UpgradeableSeiToken.sol

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

import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";

contract UpgradeableSeiToken is Initializable, ERC20Upgradeable, OwnableUpgradeable, UUPSUpgradeable {
    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers();
    }

    function initialize(address initialOwner) initializer public {
        __ERC20_init("Upgradeable Sei Token", "uSEI");
        __Ownable_init(initialOwner);

        // Mint 1 million tokens to the initializer (deployer)
        _mint(initialOwner, 1000000 * 10 ** decimals());
    }

    // Function to mint new tokens (only owner)
    function mint(address to, uint256 amount) virtual public onlyOwner {
        _mint(to, amount);
    }

    // Required for UUPS upgradeability
    function _authorizeUpgrade(address newImplementation)
        internal
        onlyOwner
        override
    {}

    // OPTIONAL: Add a version identifier (useful for tracking upgrades)
    function version() public virtual pure returns (string memory) {
        return "V1";
    }
}

The Initializable base, the initializer modifier, the __ERC20_init and __Ownable_init calls, and the _authorizeUpgrade override make the contract safe to run behind a proxy. In OpenZeppelin v5, UUPSUpgradeable is stateless, so there is no __UUPSUpgradeable_init to call.

Add a thin, named ERC1967 proxy so that Hardhat emits an artifact that you can deploy by name. Create contracts/SeiTokenProxy.sol:

contracts/SeiTokenProxy.sol

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

import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";

contract SeiTokenProxy is ERC1967Proxy {
    constructor(address implementation, bytes memory _data)
        ERC1967Proxy(implementation, _data)
    {}
}

Next, create a deployment script named scripts/deploy-upgradeable-token.ts. The script deploys the implementation first. Then it deploys the proxy with the initialize call encoded as constructor data, so initialization happens atomically:

scripts/deploy-upgradeable-token.ts

import { network } from 'hardhat';

const { ethers } = await network.create();

const [deployer] = await ethers.getSigners();
console.log('Deploying contracts with the account:', deployer.address);

// 1. Deploy the implementation contract
const UpgradeableSeiToken = await ethers.getContractFactory('UpgradeableSeiToken');
const implementation = await UpgradeableSeiToken.deploy();
await implementation.waitForDeployment();

// 2. Deploy the ERC1967 proxy, running initialize(deployer) atomically
const initData = UpgradeableSeiToken.interface.encodeFunctionData('initialize', [deployer.address]);
const SeiTokenProxy = await ethers.getContractFactory('SeiTokenProxy');
const proxy = await SeiTokenProxy.deploy(await implementation.getAddress(), initData);
await proxy.waitForDeployment();

// 3. Interact with the token through the proxy address from here on
const token = await ethers.getContractAt('UpgradeableSeiToken', await proxy.getAddress());
console.log('Proxy deployed to:', await token.getAddress());
console.log('Implementation:', await implementation.getAddress());
console.log('Version:', await token.version()); // V1

Deploy the contract to Sei Testnet:

npx hardhat run scripts/deploy-upgradeable-token.ts --network seitestnet

Upgrading the contract

To add a new feature or fix a bug, create a new version of the contract, contracts/UpgradeableSeiTokenV2.sol:

contracts/UpgradeableSeiTokenV2.sol

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

import "./UpgradeableSeiToken.sol"; // Import the V1 contract

contract UpgradeableSeiTokenV2 is UpgradeableSeiToken {
    // Add a new state variable (ensure it doesn't clash with V1 storage layout)
    uint256 public totalMintedSinceV2;

    // Override the mint function to track new mints
    function mint(address to, uint256 amount) public override onlyOwner {
        super.mint(to, amount);
        totalMintedSinceV2 += amount; // Add V2 logic
    }

    // Override the version function
    function version() public pure override returns (string memory) {
        return "V2";
    }

    // IMPORTANT: V2 does not need its own initializer or constructor for upgrades.
    // The state from V1 is preserved.
}

Next, create an upgrade script named scripts/upgrade-token.ts. Replace PROXY_ADDRESS with the proxy address that the deployment script printed.

scripts/upgrade-token.ts

import { network } from 'hardhat';

const { ethers } = await network.create();

// !! REPLACE WITH YOUR PROXY ADDRESS from the deploy step !!
const PROXY_ADDRESS = '0xYOUR_PROXY_CONTRACT_ADDRESS_HERE';

const [deployer] = await ethers.getSigners();
console.log('Upgrading contract with the account:', deployer.address);

// 1. Deploy the new implementation
const UpgradeableSeiTokenV2 = await ethers.getContractFactory('UpgradeableSeiTokenV2');
const v2Implementation = await UpgradeableSeiTokenV2.deploy();
await v2Implementation.waitForDeployment();

// 2. Point the proxy at the new implementation (UUPS upgrades are owner-gated)
const token = await ethers.getContractAt('UpgradeableSeiTokenV2', PROXY_ADDRESS);
await (await token.upgradeToAndCall(await v2Implementation.getAddress(), '0x')).wait();

console.log('Upgrade complete. Proxy remains at:', PROXY_ADDRESS);
console.log('New implementation:', await v2Implementation.getAddress());
console.log('Contract version:', await token.version()); // V2

Run the upgrade script:

npx hardhat run scripts/upgrade-token.ts --network seitestnet

You have deployed and upgraded a UUPS contract on Sei with Hardhat and OpenZeppelin.

Testing your smart contracts

Hardhat lets you test your contracts before you deploy them. Create a test file named test/sei-token-test.ts:

test/sei-token-test.ts

import { expect } from 'chai';
import { network } from 'hardhat';

describe('SeiToken', function () {
  let ethers;
  let seiToken;
  let owner;
  let addr1;
  let addr2;

  beforeEach(async function () {
    // Hardhat 3 exposes ethers through a network connection
    ({ ethers } = await network.create());

    // Get signers
    [owner, addr1, addr2] = await ethers.getSigners();

    // Deploy the token
    seiToken = await ethers.deployContract('SeiToken', [owner.address]);
  });

  describe('Deployment', function () {
    it('Should set the right owner', async function () {
      expect(await seiToken.owner()).to.equal(owner.address);
    });

    it('Should assign the total supply of tokens to the owner', async function () {
      const ownerBalance = await seiToken.balanceOf(owner.address);
      const totalSupply = await seiToken.totalSupply();
      expect(totalSupply).to.equal(ownerBalance);
    });

    it('Should have correct name and symbol', async function () {
      expect(await seiToken.name()).to.equal('Sei Token');
      expect(await seiToken.symbol()).to.equal('SEI');
    });
  });

  describe('Transactions', function () {
    it('Should transfer tokens between accounts', async function () {
      // Transfer 50 tokens from owner to addr1
      await seiToken.transfer(addr1.address, 50);
      expect(await seiToken.balanceOf(addr1.address)).to.equal(50);

      // Transfer 50 tokens from addr1 to addr2
      await seiToken.connect(addr1).transfer(addr2.address, 50);
      expect(await seiToken.balanceOf(addr2.address)).to.equal(50);
    });

    it("Should fail if sender doesn't have enough tokens", async function () {
      const initialOwnerBalance = await seiToken.balanceOf(owner.address);

      // Try to send 1 token from addr1 (0 tokens) to owner
      await expect(seiToken.connect(addr1).transfer(owner.address, 1)).to.be.reverted;

      // Owner balance shouldn't change
      expect(await seiToken.balanceOf(owner.address)).to.equal(initialOwnerBalance);
    });
  });

  describe('Minting', function () {
    it('Should allow owner to mint new tokens', async function () {
      await seiToken.mint(addr1.address, 1000);
      expect(await seiToken.balanceOf(addr1.address)).to.equal(1000);
    });

    it('Should not allow non-owners to mint', async function () {
      await expect(seiToken.connect(addr1).mint(addr1.address, 1000)).to.be.reverted;
    });
  });
});

Run your tests:

npx hardhat test

Deploying to Sei Testnet and Mainnet

After you test your contracts, you can deploy them to Sei Testnet or Sei Mainnet. To deploy, you need:

1. SEI tokens in your wallet for gas
2. Your private key stored in the encrypted keystore (npx hardhat keystore set SEI_PRIVATE_KEY), or exported as a SEI_PRIVATE_KEY environment variable in CI

Deploy to Sei Testnet:

npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seitestnet

Deploy to Sei Mainnet only when you are ready for production:

npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seimainnet