Hardhat Config 완전 정리: hardhat.config.ts 핵심 설정 가이드

이 글을 통해 독자는 Hardhat 프로젝트의 설정 구조를 한눈에 이해하고, 네트워크·컴파일·테스트·배포 설정을 실무 기준으로 구성하는 방법을 익힐 수 있습니다.

Hardhat Config란 무엇인가

hardhat.config.ts는 Hardhat 프로젝트의 중앙 제어 파일입니다.
어떤 네트워크에 연결할지, 어떤 Solidity 버전을 사용할지, 테스트와 가스 리포트를 어떻게 실행할지를 모두 이 파일에서 정의합니다.

즉, Hardhat의 동작 방식 전체를 결정하는 설계도라고 볼 수 있습니다.

기본 네트워크와 networks 설정

Hardhat은 로컬, 테스트넷, 메인넷을 모두 지원하며 이를 networks로 구분합니다.

• defaultNetwork는 명령 실행 시 기본으로 사용할 네트워크입니다.
• localhost와 hardhat은 개발 단계에서 가장 많이 사용됩니다.
• sepolia, mainnet은 실제 배포 환경을 의미합니다.

주의: 실무에서는 개인 키를 코드에 직접 쓰지 않고 .env 환경 변수를 사용합니다.

Solidity 컴파일러 설정

Solidity 설정은 보안과 가스 비용에 직접적인 영향을 줍니다.

• version으로 컴파일러 버전을 고정
• optimizer.enabled를 통해 가스 최적화 활성화
• optimizer.runs는 예상 실행 빈도 기준(보통 200)
• evmVersion으로 타겟 EVM 환경 지정

한 번 배포된 컨트랙트는 수정할 수 없기 때문에, 컴파일 단계에서의 설정이 매우 중요합니다.

폴더 경로(paths) 구조 이해

Hardhat은 기본적으로 다음 구조를 사용합니다.

• contracts: Solidity 소스
• test: 테스트 코드
• artifacts: 컴파일 결과물(ABI, Bytecode)
• cache: 빌드 캐시

경로를 명확히 나누면 대규모 프로젝트에서도 관리가 쉬워집니다.

테스트(mocha) 설정

Hardhat은 Mocha를 테스트 러너로 사용합니다.

• 배포·블록 생성 테스트는 시간이 오래 걸릴 수 있음
• timeout을 넉넉히 설정해 불필요한 테스트 실패를 방지

팁: 테스트가 자주 타임아웃된다면 네트워크 설정부터 점검하세요.

가스 리포트와 비용 가시화

gasReporter는 트랜잭션별 가스 사용량을 자동으로 분석합니다.

• 실제 USD 기준 비용 확인 가능
• 최적화 전·후 비교에 유용
• 대규모 프로젝트에서 비용 관리에 필수

Etherscan 컨트랙트 검증

배포 후 컨트랙트를 신뢰받기 위해서는 소스 코드 검증이 필요합니다.

• etherscan.apiKey에 API 키 설정
• 배포된 주소를 기준으로 검증 실행
• 검증 후 누구나 코드와 ABI를 확인 가능

정리

• Hardhat Config는 스마트 컨트랙트 개발의 중심
• 네트워크·컴파일러·테스트·배포 설정을 명확히 분리해야 함
• 환경 변수 사용은 보안의 기본
• 설정을 이해하면 배포·검증·운영까지 자연스럽게 이어짐