Alchemy Local Dev Loop

Overview

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.

Prerequisites

Completed alchemy-install-auth setup
Node.js 18+
Alchemy API key with Sepolia testnet app

Instructions

Step 1: Initialize Hardhat Project with Alchemy

mkdir 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

Step 2: Configure Hardhat with Alchemy RPC

// 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;

Step 3: Alchemy-Powered Test Helper

// 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 };

Step 4: Development Scripts

{
  "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"
  }
}

Step 5: Mainnet Fork Testing

// 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);
  });
});

Output

Hardhat project with Alchemy RPC (mainnet fork + Sepolia)
Alchemy-powered test helpers for balance checks and tx waiting
Mainnet fork testing with account impersonation
Development scripts with watch mode

Error Handling

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

Resources

Next Steps

For SDK patterns and best practices, see alchemy-sdk-patterns.

alchemy-local-dev-loop