Hardhat Production Deployment: AI-Optimized Knowledge Base

Critical Configuration Requirements

Version Pinning (Mission Critical)

• Pin ALL dependencies including linters - wrong dependency updates have bricked more deployments than any other cause
• Solidity version must be exact (e.g., "0.8.19", not "^0.8.0")
• Optimizer runs must match testing exactly (200 is standard, not 100 or 1000)
• viaIR required for complex contracts hitting stack limits

module.exports = {
  solidity: {
    version: "0.8.19", // Exact version only
    settings: {
      optimizer: { enabled: true, runs: 200 }, // Match test config exactly
      viaIR: true // For stack limit issues
    }
  }
};

Environment Isolation (Career-Saving)

• Failure Mode: Teams deploy dev contracts to mainnet when MAINNET_RPC in .env
• Solution: Use Hardhat config variables for production secrets
• Hardware wallet requirement: NEVER store mainnet private keys in .env files

Gas Management Reality

Gas Estimation Failures

• Problem: Hardhat gas estimation assumes perfect network conditions that don't exist
• Solution: 1.5x rule - multiply all estimated gas by 1.5x for mainnet
• Hidden costs: Proxy deployments need gas for both proxy AND implementation (20-30% overhead)

const deploymentTx = await factory.deploy(initArgs, {
  gasLimit: estimatedGas.mul(150).div(100), // 1.5x estimated
  gasPrice: gasPrice.mul(110).div(100),     // 10% above current
  maxFeePerGas: gasPrice.mul(150).div(100), // EIP-1559 buffer
});

Network-Specific Gas Gotchas

• Polygon: Requires 35 gwei minimum, needs 5+ confirmations
• Arbitrum: Different gas mechanics, use "auto" pricing
• Mainnet: MEV bots affect gas during congestion

RPC Provider Failure Modes

Rate Limiting Reality

• Infura: 100k requests/day on free tier
• Alchemy: Better WebSocket support, different error handling
• QuickNode: Costs more but doesn't randomly throttle

Network Configuration That Works

networks: {
  mainnet: {
    url: process.env.MAINNET_RPC_URL,
    accounts: [], // Hardware wallet only
    gasPrice: "auto",
    timeout: 60000,     // 1 minute for congestion
    confirmations: 2,   // Minimum safe confirmations
  }
}

Contract Verification Hell

Common Verification Failures

• Constructor arguments must be ABI-encoded exactly
• Library linking breaks verification if addresses don't match
• Proxy contracts need separate verification for implementation and proxy

Working Verification Config

etherscan: {
  apiKey: {
    mainnet: process.env.ETHERSCAN_API_KEY,
    polygon: process.env.POLYGONSCAN_API_KEY,
  },
  customChains: [...] // Required for L2s
},
sourcify: { enabled: true } // Backup verification

Deployment Script Failure Prevention

Pre-Flight Checks That Save Careers

// Check deployer balance before starting
const balance = await hre.ethers.provider.getBalance(deployer);
if (balance.lt(hre.ethers.utils.parseEther("0.1"))) {
  throw new Error(`Deployer needs more ETH. Current: ${hre.ethers.utils.formatEther(balance)}`);
}

Dependency Management Strategy

• Phase 1: Deploy core contracts (no dependencies)
• Phase 2: Deploy dependent contracts with Phase 1 addresses
• Phase 3: Initialize contracts (often forgotten step)
• Save addresses to files - don't hardcode between deployments

Hardware Wallet Integration

Security Requirements

• Ledger with Hardhat Ignition is the only safe approach for mainnet
• Never store private keys in .env for production deployments
• Large deployments timeout - deploy in smaller modules

npx hardhat ignition deploy ignition/modules/Protocol.ts \
  --network mainnet \
  --strategy create2 \
  --deployment-id production-v1.0.0 \
  --ledger

Production Validation Checklist

Deployment Success Verification

1. Contract address exists with correct bytecode on Etherscan
2. Contract is verified and source matches expectations
3. Initial state is correct - call getter functions manually
4. Events were emitted if constructor should emit events
5. ETH balance decreased by expected gas costs

Gas Failure Recovery Strategy

1. Check what contracts actually deployed on Etherscan
2. Update deployment script to skip successful deployments
3. Resume from failing point with proper gas estimates
4. Keep deployment state in JSON files for recovery

Multi-Network Security Considerations

Network-Specific Risks

• Bridge exploits: If protocol spans chains, bridge security = your security
• Chain reorgs: Different networks have different reorg probabilities
• Gas price manipulation: MEV opportunities vary by chain
• Contract address consistency: Use CREATE2 for identical addresses across chains

Confirmation Strategy by Risk Level

• Small amounts (<$10k): 2-3 confirmations
• Medium amounts ($10k-$100k): 5-6 confirmations
• Large amounts (>$100k): 12+ confirmations

Upgrade Pattern Implementation

Proxy Contract Deployment Reality

// OpenZeppelin upgrades add 20-30% gas overhead
const proxy = await upgrades.deployProxy(MyContract, [arg1, arg2], {
  initializer: 'initialize' // Custom initializer name
});

// Storage layout must be preserved between versions
// Cannot remove state variables, only add them
// Constructor code doesn't run - use initializers

Upgrade Gotchas That Bite Everyone

• Storage layout preservation required between versions
• No constructor execution in upgrades - use initialize functions
• Proxy admin management is separate contract responsibility

Production Monitoring Requirements

Critical Metrics to Monitor

• Contract balances - sudden changes indicate exploits
• Total Value Locked (TVL) - economic health indicator
• Transaction success rates - contract functionality health
• Gas usage patterns - efficiency and attack detection
• Admin key usage - unauthorized administrative actions

Incident Response Time Windows

• Phase 1 (0-5 minutes): Detection and assessment
• Phase 2 (5-30 minutes): Immediate response and containment
• Phase 3 (30 minutes - hours): Investigation and mitigation

Security Hardening Operational Requirements

Access Control Implementation

• Deployer accounts: Hardware wallets only
• Critical operations: 2-of-3 multi-sig approval required
• RPC keys: IP restrictions and usage monitoring
• Code signing: Required for deployment artifacts

Multi-Sig Deployment Strategy

1. Deploy from regular account for initial deployment
2. Transfer ownership to multi-signature wallet immediately
3. All critical operations require multiple signatures
4. No single person can break the protocol

Economic Cost Analysis

Direct Deployment Costs

• Contract deployment: $500-5000 depending on complexity
• Verification costs: $50-200 per contract across networks
• Failed deployment recovery: $200-2000 in wasted gas
• Upgrade operations: $300-1000 per upgrade cycle

Ongoing Operational Costs

• RPC provider fees: $100-500/month for production usage
• Block explorer API limits: $50-200/month
• Monitoring infrastructure: $200-500/month
• Multi-sig transaction fees: $20-100 per governance action

Security Incident Hidden Costs

• Emergency response team: $10,000+ per incident
• Post-incident security audit: $20,000-100,000
• Legal and compliance costs: $50,000+ for major incidents
• Reputation damage: Career-ending consequences

Deployment Strategy Risk Matrix

Approach	Risk Level	Complexity	Recovery Options	Use Case
Manual Scripts	High	Low	Manual rollback only	Prototypes only
Hardhat Ignition	Medium	Medium	Automatic retry, state tracking	Multi-contract protocols
OpenZeppelin Defender	Low	High	Full rollback, automated monitoring	Enterprise production
Custom CI/CD Pipeline	Medium	Very High	Implementation dependent	Large team operations

Critical Failure Scenarios

Testnet vs Mainnet Differences That Cause Failures

• Gas prices: Testnet gas is fake, mainnet costs real money
• Block times: Different timing affects transaction dependencies
• MEV bots: Mainnet has frontrunning, testnets usually don't
• RPC limits: Free testnet vs paid mainnet RPCs have different rate limits

Rollback Strategies by Contract Type

• Upgradeable contracts: Can upgrade to fixed/previous version
• Regular contracts: Mostly impossible - deploy new version and update references
• Prevention: Build emergency pause functionality from day 1

Common Mainnet Failure Modes

• RPC timeouts during high network congestion
• Gas price estimation too low during busy periods
• Contract size limits (24KB) hit on mainnet but not testnets
• EIP-1559 gas pricing differences between networks

Emergency Response Automation

Automated Incident Response

const emergencyResponse = async (incidentType) => {
  // Step 1: Immediate containment
  if (await vault.paused() === false) {
    await vault.emergencyPause(); // Requires multi-sig
  }
  
  // Step 2: Stakeholder notification
  await sendSlackAlert(`🔥 CRITICAL INCIDENT: ${incidentType}`);
  
  // Step 3: State snapshot for investigation
  const snapshot = {
    blockNumber: await provider.getBlockNumber(),
    contractBalances: await getContractBalances(),
    recentTransactions: await getRecentTransactions()
  };
  fs.writeFileSync(`incident-${Date.now()}.json`, JSON.stringify(snapshot, null, 2));
};

This knowledge base contains all actionable intelligence for implementing secure, production-ready Hardhat deployments while avoiding the costly mistakes that destroy protocols and careers.