Set up local Web3 development workflow with Alchemy, Hardhat, and testnets. Use when configuring local blockchain dev, testing with Sepolia faucets, or setting up hot-reload for smart contract development. Trigger: "alchemy local dev", "alchemy hardhat", "alchemy testnet setup".
Local Web3 development workflow using Alchemy as the RPC provider with Hardhat for local testing, Sepolia testnet for staging, and hot-reload for rapid iteration.
alchemy-install-auth setupmkdir web3-project && cd web3-project
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npm install alchemy-sdk dotenv
npx hardhat init # Select TypeScript project
// hardhat.config.ts
import { HardhatUserConfig } from 'hardhat/config';
import '@nomicfoundation/hardhat-toolbox';
import 'dotenv/config';
const config: HardhatUserConfig = {
solidity: '0.8.24',
networks: {
hardhat: {
forking: {
url: `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`,
blockNumber: 19000000, // Pin block for reproducible tests
},
},
sepolia: {
url: `https://eth-sepolia.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`,
accounts: process.env.DEPLOYER_PRIVATE_KEY ? [process.env.DEPLOYER_PRIVATE_KEY] : [],
},
},
};
export default config;
// test/helpers/alchemy-helper.ts
import { Alchemy, Network } from 'alchemy-sdk';
const alchemy = new Alchemy({
apiKey: process.env.ALCHEMY_API_KEY,
network: Network.ETH_SEPOLIA,
});
export async function getTestnetBalance(address: string): Promise<string> {
const balance = await alchemy.core.getBalance(address);
return (parseInt(balance.toString()) / 1e18).toFixed(4);
}
export async function waitForTransaction(txHash: string): Promise<any> {
return alchemy.core.waitForTransaction(txHash, 1, 60000);
}
export { alchemy };
{
"scripts": {
"dev": "npx hardhat node --fork https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}",
"test": "npx hardhat test",
"test:watch": "npx hardhat test --watch",
"deploy:sepolia": "npx hardhat run scripts/deploy.ts --network sepolia",
"verify": "npx hardhat verify --network sepolia"
}
}
// test/fork-test.ts
import { expect } from 'chai';
import { ethers } from 'hardhat';
describe('Mainnet Fork Tests', () => {
it('should read USDC balance on forked mainnet', async () => {
const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
const usdc = await ethers.getContractAt('IERC20', USDC);
const totalSupply = await usdc.totalSupply();
expect(totalSupply).to.be.gt(0);
});
it('should impersonate whale account', async () => {
const whale = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
await ethers.provider.send('hardhat_impersonateAccount', [whale]);
const signer = await ethers.getSigner(whale);
const balance = await ethers.provider.getBalance(whale);
expect(balance).to.be.gt(0);
});
});
| Error | Cause | Solution |
|---|---|---|
| Fork timeout | Alchemy rate limit | Pin block number; upgrade plan |
ProviderError: missing trie node | Stale fork block | Use more recent block number |
| Sepolia deploy fails | Insufficient test ETH | Get from Alchemy Sepolia faucet |
nonce too low | Stale nonce cache | Reset Hardhat network or clear nonce |
For SDK patterns and best practices, see alchemy-sdk-patterns.