EIP-3155 EVM 트레이스 표준 형식 (EVM trace specification)
콜 결정 없음 · EVM·실행 · 원문 상태 Last Call · 2020-12-07 작성
이더리움 클라이언트가 EVM 실행 과정을 한 단계씩 기록하는 트레이스(trace)를 공통 JSON 형식으로 표준화합니다. 모든 클라이언트가 같은 형식으로 로그를 남기게 됩니다.
왜 필요한가
이더리움에는 Go-Ethereum, Besu, Nethermind 같은 여러 클라이언트가 있고 모두 같은 규칙으로 스마트 컨트랙트를 실행해야 합니다. 실행 과정을 들여다보려고 각 클라이언트는 명령어 하나하나를 기록하는 트레이스 기능을 이미 구현해 두었지만 공통 형식이 엄밀하게 정의되지 않아 구현마다 출력이 조금씩 달랐습니다. 형식이 다르면 여러 클라이언트의 실행 결과를 자동으로 비교하는 도구를 만들기 어렵고 트레이스의 쓸모가 크게 줄어듭니다. 이 EIP는 형식을 눈에 잘 띄는 곳에 공식 명세로 옮기고 이전 버전에서 다루지 않던 코너 케이스를 엄밀히 정의합니다. 모든 주요 클라이언트가 이를 구현하면 메인넷과 다가올 하드포크의 EVM 구현을 서로 비교하는 차등 퍼징(differential fuzzing) 인프라를 만들 수 있고 클라이언트에 숨어 있는 버그를 찾거나 체인 분리가 생겼을 때 실행 차이를 빠르게 짚어낼 수 있습니다.
무엇이 바뀌나
지금
- 클라이언트마다 트레이스 JSON 형식이 조금씩 다릅니다
- 코너 케이스 처리 방식이 정의되어 있지 않습니다
- 형식이 제각각이라 클라이언트 간 실행 결과를 자동 비교하는 도구를 만들기 어렵습니다
EIP-3155 이후
- 모든 클라이언트가 같은 JSON 형식으로 실행 단계를 기록합니다
- 빈 배열 초기화, 에러 시 출력 규칙 같은 코너 케이스가 명확해집니다
- 클라이언트 구현을 서로 맞대어 검사하는 차등 퍼징이 가능해집니다
- 체인 분리가 생기면 어느 실행 단계에서 달라졌는지 빠르게 찾을 수 있습니다
누구에게 영향이 있나
- 클라이언트 팀: Go-Ethereum은 이미 이 형식을 따르고 OpenEthereum, Besu, Nethermind는 기존 트레이스 도구의 JSON 출력을 조금 수정해야 합니다.
- 테스트·보안 인프라 개발자: 여러 클라이언트의 트레이스를 한 줄씩 비교하는 차등 퍼저와 디버깅 도구를 공통 형식 위에서 만들 수 있습니다.
- 스마트 컨트랙트 개발자: 어떤 클라이언트에서 추적하든 같은 형식의 실행 로그를 얻어 디버깅이 쉬워집니다.
- 일반 사용자: 프로토콜 규칙은 그대로이므로 직접 바뀌는 것은 없고 클라이언트 버그가 빨리 발견되는 간접 효과를 얻습니다.
심층 설명
연산별 출력의 필수 필드
CUT는 모든 연산마다 JSON 객체 하나를 출력해야 합니다(MUST). 필수 필드는 pc(Number, 프로그램 카운터), op(Number, 옵코드), gas(Hex-Number, 연산 실행 전 남은 가스), gasCost(Hex-Number, 이 연산의 가스 비용), memSize(Number, 메모리 배열 크기), stack(Hex-Number 배열, 스택의 모든 값), depth(Number, 콜 스택 깊이), returnData(Hex-String, 함수 호출이 반환한 데이터), refund(Number, 전역 가스 환불량)입니다. 데이터 타입은 일반 숫자(Number), 16진수 숫자(Hex-Number), 문자열, 16진수 문자열, 배열, 키-값, 불리언으로 구분해 정의합니다.
선택 필드와 생략 규칙
opName(String, 연산 이름), error(Hex-String, 에러 설명이며 지원 시 revert 사유 포함), memory(Hex-String 배열), storage(Key-Value)는 선택 필드입니다. CUT가 memory나 storage 값을 출력하지 않는 경우(추적 미지원 또는 설정으로 끈 경우) 해당 필드 자체를 생략합니다. 다만 memSize는 memory 지원 여부와 관계없이 반드시 있어야 합니다(MUST). 상태 루트가 모든 스토리지 변경을 이미 반영하므로, 클라이언트는 스토리지 기록을 끌 수 있는 방법을 구현해야 합니다(SHOULD). 필드 출력 순서도 명세에 적힌 순서를 따라야 합니다(SHOULD).
값의 기준 시점과 코너 케이스
stack, memory, memSize는 해당 연산을 실행하기 전의 값입니다. 배열 속성(stack, memory)은 null이 아니라 빈 배열("stack":[])로 초기화해야 합니다(MUST). 에러가 발생한 경우 STOP 연산에 대한 줄을 출력해서는 안 됩니다(MUST NOT). 이렇게 이전 명세에서 구현마다 달랐던 세부 동작을 못 박아 클라이언트 간 출력을 줄 단위로 비교할 수 있게 합니다.
실행 종료 시 요약과 에러 처리
실행이 끝나면 CUT는 요약 정보를 jsonl 객체 하나로 출력해야 합니다(MUST). 필수 필드는 stateRoot(Hex-String, 트랜잭션 실행 후 상태 트라이의 루트), output(함수 반환값), gasUsed(Hex-Number, 트랜잭션이 쓴 전체 가스), pass(Boolean, 트랜잭션 성공 여부)입니다. 선택 필드로 time(Number, 실행에 걸린 시간을 나노초로)과 fork(String, 실행에 적용한 포크 규칙 이름)를 둘 수 있습니다.
기존 클라이언트와의 호환성
이 EIP는 선택적인 추적 인프라만 추가하므로 이더리움 프로토콜과는 완전히 하위 호환됩니다. Go-Ethereum과는 이미 완전히 호환되고 OpenEthereum(openethereum-evm), Besu(evmtool), Nethermind(nethtest)는 더 엄격해진 명세에 맞게 JSON 출력을 약간 수정해야 합니다. 새 클라이언트가 차등 퍼징 그룹에 참여하려면 이 형식을 구현해야 합니다. 원문에는 Besu evmtool로 샘플 코드를 실행해 얻은 전체 트레이스 예시가 테스트 케이스로 실려 있습니다.
보안 고려 사항
추적은 비용이 큰 작업입니다. 트레이스 생성 엔드포인트를 외부에 공개하면 서비스 거부(DoS) 공격 통로가 될 수 있습니다. 그래서 클라이언트는 트레이스 엔드포인트를 다른 엔드포인트와 분리된 별도 플래그 뒤에 두는 것을 고려해야 합니다.
진행 상태
이 EIP는 2020년 12월 7일에 만들어졌고 현재 상태는 Last Call이며 마지막 의견 수렴 기한(last-call-deadline)은 2025년 3월 1일입니다. Last Call은 최종 확정 전 마지막 검토 단계로, 이 기간의 피드백에 따라 세부 내용이 바뀔 수 있습니다. 분류는 Standards Track의 Interface 카테고리로, 합의 규칙이 아니라 클라이언트 인터페이스에 관한 표준입니다.