If you are writing a token for a project, a DAO or a client, the safest starting point is not a blank file. It is a battle-tested library plus a handful of tests that pin down the behavior you promised. In this post I'll build a small capped ERC-20 with OpenZeppelin v5, test it with Hardhat 3 and ethers, and then add linear vesting for a team allocation using OpenZeppelin's VestingWallet.
I write Solidity for clients on Ethereum, BSC and Polygon, and the pattern is always the same: use audited building blocks, keep your own code tiny, and test every promise in the whitepaper. This token is deliberately simple so you can see each moving part.
Education, not a launch guide. This code has not been audited. Do not deploy it with real funds without a professional review, and note that an owner who can mint is a trust assumption your users will care about.
What we're building
- An ERC-20 named "Team Token" (
TEAM) with no tokens at deployment. - A hard cap on total supply, enforced by OpenZeppelin's
ERC20Capped. - An owner-only
mintfunction, so supply can be created up to the cap, never beyond it. - A vesting wallet that releases a team allocation to a beneficiary linearly over 100 days.
Step 1: set up the project
Hardhat 3 requires a recent Node.js (its docs list 22.13 or later). Create an empty folder and initialize with the Mocha and ethers template, which is the setup most Ethereum developers already know:
mkdir team-token && cd team-token
npx hardhat --init --template mocha-ethers
npm install @openzeppelin/contracts
Run npx hardhat --init --templates to see the available templates. The init step creates a sample Counter contract and test. Delete those; we won't need them.
Step 2: the token contract
Two things in this file are different from older tutorials, and both are OpenZeppelin v5 changes. First, Ownable now takes the initial owner as a constructor argument instead of silently using msg.sender. Second, the old _beforeTokenTransfer hook is gone. In v5, mints, burns and transfers all pass through a single internal _update function, and because both ERC20 and ERC20Capped define it, your contract must say how they combine.
TeamToken.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import {ERC20Capped} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
/// @notice Fixed-cap ERC-20. The owner can mint until the cap is reached.
contract TeamToken is ERC20, ERC20Capped, Ownable {
constructor(address initialOwner, uint256 cap_)
ERC20("Team Token", "TEAM")
ERC20Capped(cap_)
Ownable(initialOwner)
{}
function mint(address to, uint256 amount) external onlyOwner {
_mint(to, amount);
}
// ERC20 and ERC20Capped both override _update in OpenZeppelin v5,
// so the compiler makes us pick how they combine.
function _update(address from, address to, uint256 value)
internal
override(ERC20, ERC20Capped)
{
super._update(from, to, value);
}
}
The empty override is not boilerplate for its own sake. Solidity refuses to compile an inherited function that comes from two parents until you resolve it explicitly, which is a useful guardrail. The cap itself is checked inside ERC20Capped's version of _update whenever tokens are minted (a transfer from the zero address).
Step 3: a vesting contract
For a team allocation you rarely want to hand over everything on day one. OpenZeppelin ships VestingWallet, which holds tokens and releases them to a beneficiary on a linear schedule between a start time and a duration. It handles ETH and any ERC-20 sent to it.
One practical wrinkle I hit: importing a contract from an npm package into another contract does not make Hardhat produce a deployable artifact for it. The simple fix is a one-line wrapper contract in your own contracts folder:
TeamVesting.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {VestingWallet} from "@openzeppelin/contracts/finance/VestingWallet.sol";
/// @notice Thin wrapper so Hardhat builds an artifact we can deploy by name.
contract TeamVesting is VestingWallet {
constructor(address beneficiary, uint64 startTimestamp, uint64 durationSeconds)
VestingWallet(beneficiary, startTimestamp, durationSeconds)
{}
}
Step 4: tests that pin down your promises
I write tests for every sentence I would put in documentation. Here, that means: metadata is right, only the owner can mint, the cap really is a ceiling, a sender cannot spend more than they hold, and vesting releases the right amount at the halfway point.
OpenZeppelin v5 uses custom errors instead of revert strings, so the tests assert with revertedWithCustomError. That is also cheaper in gas than a string. The vesting test moves the simulated clock with networkHelpers.time.increaseTo, so a 100-day schedule runs in milliseconds.
TeamToken.ts
import { expect } from "chai";
import { network } from "hardhat";
const { ethers, networkHelpers } = await network.create();
const CAP = ethers.parseEther("1000000");
async function deployFixture() {
const [owner, alice, bob] = await ethers.getSigners();
const token = await ethers.deployContract("TeamToken", [owner.address, CAP]);
return { token, owner, alice, bob };
}
describe("TeamToken", function () {
it("starts with zero supply and the right metadata", async function () {
const { token } = await networkHelpers.loadFixture(deployFixture);
expect(await token.name()).to.equal("Team Token");
expect(await token.symbol()).to.equal("TEAM");
expect(await token.totalSupply()).to.equal(0n);
expect(await token.cap()).to.equal(CAP);
});
it("lets only the owner mint", async function () {
const { token, alice } = await networkHelpers.loadFixture(deployFixture);
await expect(token.connect(alice).mint(alice.address, 1n))
.to.be.revertedWithCustomError(token, "OwnableUnauthorizedAccount")
.withArgs(alice.address);
});
it("refuses to mint past the cap", async function () {
const { token, alice } = await networkHelpers.loadFixture(deployFixture);
await token.mint(alice.address, CAP);
await expect(token.mint(alice.address, 1n))
.to.be.revertedWithCustomError(token, "ERC20ExceededCap")
.withArgs(CAP + 1n, CAP);
});
it("reverts when a sender transfers more than they hold", async function () {
const { token, alice, bob } = await networkHelpers.loadFixture(deployFixture);
await token.mint(alice.address, 10n);
await expect(token.connect(alice).transfer(bob.address, 11n))
.to.be.revertedWithCustomError(token, "ERC20InsufficientBalance");
});
it("vests linearly through an OpenZeppelin VestingWallet", async function () {
const { token, bob } = await networkHelpers.loadFixture(deployFixture);
const start = (await ethers.provider.getBlock("latest"))!.timestamp + 60;
const duration = 100 * 24 * 60 * 60; // 100 days
const wallet = await ethers.deployContract("TeamVesting", [bob.address, start, duration]);
const total = ethers.parseEther("1000");
await token.mint(await wallet.getAddress(), total);
// Before the start time nothing is releasable.
expect(await wallet["releasable(address)"](await token.getAddress())).to.equal(0n);
// Halfway through, about half is releasable.
await networkHelpers.time.increaseTo(start + duration / 2);
const half = await wallet["releasable(address)"](await token.getAddress());
expect(half).to.equal(total / 2n);
await wallet["release(address)"](await token.getAddress());
expect(await token.balanceOf(bob.address)).to.be.gte(total / 2n);
});
});
Run the suite:
npx hardhat test mocha
This is what I saw:
TeamToken
✔ starts with zero supply and the right metadata
✔ lets only the owner mint
✔ refuses to mint past the cap
✔ reverts when a sender transfers more than they hold
✔ vests linearly through an OpenZeppelin VestingWallet
5 passing
How the vesting test works
The test deploys TeamVesting with the beneficiary, a start time 60 seconds in the future, and a duration of 100 days. It mints 1,000 tokens straight into the wallet, which is how you fund a vesting wallet: the contract simply holds the balance. Before the start, nothing is releasable. After jumping to the halfway point, exactly half is. Calling release sends that half to the beneficiary.
Notice the function selectors like wallet["releasable(address)"]. VestingWallet has overloaded functions, one for ETH and one for a token address, so ethers needs the full signature to know which you mean.
Two small details that trip people up
Decimals. OpenZeppelin's ERC20 uses 18 decimals unless you override decimals(). That is why the tests use ethers.parseEther("1000000"): it is simply a convenient way to write a number with 18 zeros of precision. If you build a token with 6 decimals, use ethers.parseUnits instead, and write your cap in the same units, or you will be off by a factor of a trillion.
The fixture. loadFixture runs your deployment once, takes a snapshot and rewinds to it for each test. That keeps tests independent without paying for a fresh deployment every time, and it matters more as your setup grows from one contract to ten.
Mistakes I see in token contracts
- Writing custom token logic instead of reusing the library. Bugs tend to hide in the clever parts. Keep the clever parts small and put them in tests.
- Testing only the happy path. The interesting tests are the reverts: wrong caller, over the cap, not enough balance.
- Skipping time-based tests. Vesting and lockups depend on timestamps, and a bug there only shows up months later unless you move the clock in a test.
- Leaving ownership on a single hot wallet. Decide who can mint or pause before launch, and write it down.
Security notes before you go further
- An owner who can mint is centralization. If you promise a fixed supply, either mint it all at deployment and renounce the minting power, or move ownership to a multisig, and say so publicly.
- The cap is not a price promise. It only limits supply.
- Check who the beneficiary is. A vesting wallet is owned by its beneficiary. If you set the wrong address, the tokens belong to the wrong person.
- Test on a public testnet next, then get an independent review before any mainnet deployment with real value.
- Verify the source on a block explorer after deployment so users can read what they interact with.
Where to go from here
You now have the skeleton of most token projects: a capped supply, a controlled minter and a schedule. Natural next steps are adding ERC20Burnable, adding ERC20Permit for gasless approvals, moving to a multisig owner, and writing a Hardhat Ignition module to make deployments repeatable.
Need a token, vesting or staking contract built properly?
I build and test EVM smart contracts, plus the React and Node.js front ends around them, for clients on Ethereum, BSC and Polygon. If you have a spec, I can tell you what it needs.
See smart-contract services Get in touchWhat I ran this against
- Hardhat 3.22.0 (Mocha + ethers template), @openzeppelin/contracts 5.6.1, ethers 6.17, solc 0.8.34, Node.js 24.22.1. All 5 tests below passed on 17 November 2026.
- Everything ran on Hardhat's in-process simulated network only. Nothing was deployed to a testnet or mainnet, and the contracts have not been audited.
- I have not re-tested this on Hardhat 2. The
network.create()andnetworkHelperscalls are Hardhat 3 APIs.
Sources checked
- Hardhat 3 getting-started guide (Node.js 22.13 or later required;
--inittemplates): hardhat.org/docs/getting-started, read 17 November 2026. - OpenZeppelin Contracts 5.0 release notes (
Ownablenow takes aninitialOwner): GitHub release v5.0.0-rc.0. - OpenZeppelin finance contracts documentation (
VestingWallet): docs.openzeppelin.com.