EIP-7949 제네시스 파일 표준 형식 (Genesis File Format)
콜 결정 없음 · 네트워크·노드 · 원문 상태 Draft · 2025-05-19 작성
이더리움 네트워크를 처음 시작할 때 쓰는 설정 파일인 genesis.json의 표준 구조를 정합니다. Geth가 쓰는 사실상의 표준 구조를 공식화하고 검증용 JSON 스키마를 제공합니다.
왜 필요한가
이더리움 네트워크는 첫 블록(제네시스 블록)의 내용과 체인 설정을 담은 genesis.json 파일을 읽으며 시작합니다. 그런데 지금까지 이 파일의 공식 표준이 없었습니다. 각 클라이언트(노드 소프트웨어)가 Geth의 형식을 비슷하게 따라 하면서도 세부가 조금씩 달라 여러 클라이언트를 함께 돌리는 테스트 네트워크에서 호환성 문제와 버그, 혼란이 생겼고 운영자의 작업량도 늘었습니다. 이 EIP는 모든 클라이언트가 같은 구조를 쓰도록 필드 이름과 형식을 명문화하고 기계가 자동으로 검사할 수 있는 JSON 스키마(JSON Schema)를 붙여 모호함을 줄이는 것이 목적입니다. 새 체인 설정 관련 EIP들이 계속 나오는 상황에서, 그 변경이 얹힐 바탕 문서를 먼저 정해 두려는 제안이기도 합니다.
무엇이 바뀌나
지금
- genesis.json의 공식 표준이 없고 Geth 구현이 사실상의 기준입니다
- 클라이언트마다 세부 형식이 달라 멀티 클라이언트 테스트넷에서 호환성 문제가 생깁니다
- 파일이 맞게 작성됐는지 자동으로 검사할 공통 수단이 없습니다
EIP-7949 이후
- 최상위 필드, config, alloc 등 표준 구조가 문서로 정해집니다
- 모든 클라이언트가 같은 구조를 읽어 네트워크 구성이 쉬워집니다
- JSON 스키마로 파일을 작성 즉시 자동 검증할 수 있습니다
누구에게 영향이 있나
- 클라이언트 팀: 제네시스 파일 파싱을 공통 스키마에 맞출 수 있어 클라이언트 간 불일치와 버그가 줄어듭니다.
- 테스트넷·데브넷 운영자: 여러 클라이언트를 함께 띄울 때 하나의 genesis.json을 그대로 쓸 수 있고 스키마 검증으로 설정 실수를 미리 잡습니다.
- 개발 도구 제작자: 스키마 기반으로 제네시스 파일 생성기, 검증기, 에디터 자동완성 같은 도구를 만들 수 있습니다.
심층 설명
최상위 필드 구성
제네시스 파일은 JSON 객체이며 최상위에 config(체인 설정 객체), alloc(주소별 초기 상태 맵), nonce, timestamp, extraData, gasLimit, difficulty, mixhash, coinbase 필드를 둡니다. 수치 필드는 16진수 문자열로 적습니다. 예를 들어 gasLimit은 0x1c9c380, difficulty는 0x1, coinbase는 0x0000000000000000000000000000000000000000 같은 형식입니다. JSON 스키마상 필수 필드는 alloc, gasLimit, difficulty 세 개이고 정의되지 않은 추가 최상위 속성은 허용됩니다(additionalProperties: true).
config 객체: 체인 식별과 하드포크 일정
config 객체는 체인 식별자와 하드포크 활성화 시점을 담습니다. chainId는 10진 정수로 적습니다(메인넷은 1). 하드포크 활성화는 <hardfork(Block|Time)> 형태의 키에 블록 높이 또는 타임스탬프를 10진 정수로 적습니다. 예시는 shanghaiTime: 1681338455입니다. 스키마에는 homesteadBlock부터 londonBlock, arrowGlacierBlock, grayGlacierBlock 같은 블록 기반 포크와 shanghaiTime, cancunTime, pragueTime, osakaTime 같은 시간 기반 포크 키가 열거되어 있습니다. 작업증명에서 지분증명으로 전환하는 기준인 terminalTotalDifficulty는 16진수 문자열로, 예치 컨트랙트 주소 depositContractAddress는 주소 형식 16진수 문자열로 적습니다.
blobSchedule 객체: 포크별 블롭 파라미터
config 안의 blobSchedule은 하드포크 이름을 키로, EIP-4844 블롭 설정 파라미터를 값으로 갖는 맵입니다. 각 항목에는 10진 정수 필드가 세 개 있습니다. target은 블록당 목표 블롭 수(예: 3), max는 블록당 최대 블롭 수(예: 6), baseFeeUpdateFraction은 EIP-4844 가격 공식에 들어가는 입력값(예: 3338477)입니다. 이 구조는 블롭 스케줄을 실행 클라이언트 설정 파일에 넣기로 한 EIP-7840의 설정 방식을 따릅니다.
alloc 객체: 제네시스 초기 상태
alloc은 제네시스 시점의 초기 상태를 정의합니다. 16진수 주소 문자열을 키로 하고, 값 객체에는 balance(웨이 단위 잔액, 16진수 문자열, 예: 0xde0b6b3a7640000은 1 ETH), code(EVM 바이트코드 16진수 문자열), nonce(계정 논스 16진수 문자열), storage(32바이트 16진수 문자열 키와 값으로 된 스토리지 슬롯 맵)를 둘 수 있습니다. 이를 이용해 네트워크 시작 시점부터 특정 계정에 잔액을 주거나 컨트랙트 코드와 스토리지를 미리 배포해 둘 수도 있습니다.
JSON 스키마와 형식 규칙
원문은 draft-07 기반 JSON 스키마 전문을 제공합니다. 공통 형식은 $defs로 정의합니다. hexUint는 ^0x[0-9a-fA-F]+$, address는 40자리 16진수, hash는 소문자 64자리 16진수 패턴입니다. alloc의 주소 키는 ^0x[0-9a-fA-F]{40}$ 패턴으로 검사하고 code는 소문자 16진수만 허용하는 ^0x([0-9a-f])*$ 패턴입니다. extraData는 빈 문자열이거나 짝수 길이 16진수 문자열(^0x([0-9a-fA-F]{2})*$)이어야 합니다. config는 열거된 키 외의 추가 속성을 허용하지만(additionalProperties: true), alloc 값 객체는 허용하지 않습니다.
왜 지금 표준화하는가
제네시스 설정을 고치거나 확장하는 EIP가 늘고 있습니다. 원문은 블롭 스케줄을 실행 클라이언트 설정에 추가하는 EIP-7840, 블롭 파라미터만 바꾸는 하드포크를 정의한 EIP-7892, 노드 설정을 조회하는 eth_config JSON-RPC 메서드인 EIP-7910을 예로 듭니다. 이들이 수정하는 루트 설정 요소 자체가 지금까지 명세되지 않았기 때문에, 최소한의 스키마를 먼저 정해 두면 후속 변경을 더 정확하고 간결하게 기술할 수 있다는 것이 이 EIP의 논거입니다.
보안 영향과 현재 상태
이 EIP는 Informational 유형으로, 선택적이며 개발 편의를 제공하는 문서입니다. 제네시스 파일은 노드 관리자 권한으로만 사용되므로 새로운 보안 우려는 없다고 원문은 밝힙니다. 네트워크 하드포크가 필요한 프로토콜 변경이 아니라 클라이언트와 도구가 따를 문서 표준입니다. 현재 상태는 Draft이므로 필드 구성과 스키마 세부는 앞으로 바뀔 여지가 있습니다.