;
};
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](/evm/videos) 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](#try-it-before-you-install)
* [Prerequisites](#prerequisites)
* [Setting up your development environment](#setting-up-your-development-environment)
* [Configuring Hardhat for Sei EVM](#configuring-hardhat-for-sei-evm)
* [Using OpenZeppelin contracts](#using-openzeppelin-contracts)
* [Creating and deploying an ERC20 token, ERC721 NFT or an upgradeable UUPS token](#creating-and-deploying-an-erc20-token)
* [Testing your smart contracts](#testing-your-smart-contracts)
* [Deploying to Sei Testnet and Mainnet](#deploying-to-sei-testnet-and-mainnet)
## Prerequisites
Before you start, make sure that you have installed these tools:
* [Node.js](https://nodejs.org/) (v18.0.0 or later)
* [npm](https://www.npmjs.com/) (v7.0.0 or later) or [yarn](https://yarnpkg.com/)
* A code editor (VS Code recommended)
## Setting up your development environment
Create a new project and set up Hardhat:
```bash theme={null}
# 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:
```bash theme={null}
npm install @openzeppelin/contracts
```
For a non-interactive setup (CI or scripted environments), do the same steps manually, without prompts:
```bash theme={null}
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:
```typescript title="hardhat.config.ts" theme={null}
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:
```bash theme={null}
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
To create a simple ERC20 token with OpenZeppelin contracts, add a new file named `SeiToken.sol` to the `contracts` directory:
```solidity title="contracts/SeiToken.sol" theme={null}
// 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:
```typescript title="ignition/modules/deploy-sei-token.ts" theme={null}
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:
```bash theme={null}
npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seitestnet
```
To create an ERC721 NFT contract, add a new file named `SeiNFT.sol` to the `contracts` directory:
```solidity title="contracts/SeiNFT.sol" theme={null}
// 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`:
```typescript title="scripts/deploy-sei-nft.ts" theme={null}
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:
```bash theme={null}
npx hardhat run scripts/deploy-sei-nft.ts --network seitestnet
```
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:
```bash theme={null}
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`](https://www.npmjs.com/package/@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`:
```solidity title="contracts/UpgradeableSeiToken.sol" theme={null}
// 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`:
```solidity title="contracts/SeiTokenProxy.sol" theme={null}
// 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:
```typescript title="scripts/deploy-upgradeable-token.ts" theme={null}
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:
```bash theme={null}
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`:
```solidity title="contracts/UpgradeableSeiTokenV2.sol" theme={null}
// 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.**
```typescript title="scripts/upgrade-token.ts" theme={null}
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:
```bash theme={null}
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`:
```typescript title="test/sei-token-test.ts" theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seitestnet
```
Deploy to Sei Mainnet only when you are ready for production:
```bash theme={null}
npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seimainnet
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.