Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/alchemy-pack/skills/alchemy-local-dev-loop/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill alchemy-local-dev-loop. Copyright stays with the author (MIT).

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

Examples

Create a local Hardhat project using a development-only Alchemy key, pin the fork block, and run the included read-only USDC test. Treat account impersonation as a local fork feature only: it must never be pointed at a live RPC endpoint or used to represent authorization in an application. Next, deploy a deliberately disposable contract to Sepolia with a separately scoped testnet signer and wait for its confirmation. If the fork cannot be created, the testnet signer lacks funds, or a transaction remains pending beyond the timeout, stop the script, inspect sanitized network status, and correct the fixture or testnet configuration before retrying.

Error Handling

Resources

• Hardhat Alchemy Guide
• Alchemy Sepolia Faucet
• Alchemy Docs

Next Steps

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