학습

Hardhat 학습 환경 정리 노트

CryptoZombies/Hardhat 샘플을 관찰자 시점으로 분석해 표준 셋업과 흔한 함정을 정리한 학습 문서

study-docs최근 업데이트 2026년 5월 13일

개요

Solidity/Hardhat 입문 단계에서 흔히 쓰이는 CryptoZombies + Hardhat 샘플 프로젝트를 관찰자 시점으로 분석한 학습 노트 레포지토리입니다. 코드 자체보다는 TypeScript 기반 hardhat.config.ts 설정, contracts/scripts/test 표준 디렉토리 구조, .gitignore 관리 패턴 등 해당 도메인에서 반복적으로 나타나는 셋업 방식에 초점을 맞췄습니다. 컴파일부터 배포, 콘솔 호출, 테스트까지 이어지는 Hardhat 워크플로우를 아키텍처 문서로 정리했고, .env 관리 실수·node_modules 폭주·typechain 산출물 커밋·Solidity 버전 불일치 같은 자주 발생하는 함정을 별도로 기록했습니다. 실제 프로덕션 코드가 아니라 학습 자료를 대상으로 한 문서화이며, README/ARCHITECTURE/LESSONS/STACK 4개 문서로 구성되어 있습니다.

담당 역할

CryptoZombies/Hardhat 학습 샘플을 관찰자 시점으로 분석해 아키텍처와 흔한 함정을 한국어 문서로 정리했습니다.

아키텍처 다이어그램

레포지토리 분석 결과를 바탕으로 자동 생성된 구조도입니다.

아키텍처

Hardhat 빌드 흐름

contracts 소스가 compile을 거쳐 artifacts/cache/typechain으로 산출되고, 이를 test와 scripts가 사용하는 전체 흐름을 보여줍니다.

다이어그램을 그리는 중…

시퀀스

학습 진행 시 일반적 흐름

로컬 체인 기동부터 배포, 콘솔 호출, 테스트까지 개발자가 Hardhat을 다루는 순서를 나타냅니다.

다이어그램을 그리는 중…

기술스택

각 기술을 이 프로젝트에서 어떤 용도로 썼는지 정리했습니다.

프레임워크

HardhatSolidity 컴파일, 로컬 체인 실행, 테스트, 배포를 통합 관리

언어

Solidity스마트 컨트랙트 소스 작성 언어
TypeScripthardhat.config.ts 및 배포/테스트 스크립트 작성

블록체인

ethers.jsRPC 호출 및 트랜잭션 서명, 컨트랙트와의 상호작용
OpenZeppelinERC20/ERC721/Ownable 등 표준 컨트랙트 구현체 참조

도구

typechainSolidity ABI를 TypeScript 타입으로 변환

핵심 포인트

hardhat.config.ts 기반 TypeScript 설정과 표준 contracts/scripts/test 트리를 정리
compile → artifacts/cache/typechain → test/scripts로 이어지는 빌드 흐름을 문서화
.env, node_modules, 컴파일 산출물 등 커밋 시 자주 누락되는 .gitignore 패턴을 점검
환경변수 단언(!) 사용 시 발생하는 NaN/invalid hex 에러 등 학습 단계 흔한 함정을 기록
Hardhat 대비 Foundry, Truffle 등 대안 도구와의 비교 관점을 정리

문제와 해결

문제hardhat.config.ts에서 process.env.PRIVATE_KEY! 처럼 단언을 사용하면 .env 누락 시 undefined가 그대로 전달되어 ethers가 NaN/invalid hex 에러를 던짐

해결단언 대신 명시적 fallback을 두거나 dotenv의 config({ path }) 명시를 권장하는 방식으로 정리

문제hardhat.config.ts의 solidity.version과 컨트랙트 상단 pragma 버전이 어긋나면 컴파일이 실패함

해결학습 자료를 따라할 때 config와 pragma 버전을 맞춰야 한다는 점을 문서로 명시

문제artifacts, cache, typechain-types 같은 컴파일 산출물이 .gitignore에서 빠지면 repo가 빠르게 거대해지고 ABI 변경마다 큰 diff가 발생

해결컴파일 산출물은 절대 커밋하지 않고 .gitignore에 포함하는 것을 원칙으로 정리

레포지토리 정보

생성: 2026년 5월 13일
최근 커밋: 2026년 5월 13일
크기: 4 KB
라이선스: 없음

이 문서는 2026년 7월 26일 에 자동 분석으로 생성되었습니다.