EIP-8178 엔진 API 바이너리 SSZ 전송 (Binary SSZ Transport for the Engine API)
콜 결정 없음 · 네트워크·노드 · 원문 상태 Draft · 2026-03-01 작성
합의 레이어와 실행 레이어가 주고받는 엔진 API 통신에 JSON-RPC 대신 쓸 수 있는 바이너리 SSZ 전송을 추가합니다. 전송 크기가 약 50% 줄어듭니다.
왜 필요한가
이더리움 노드는 합의 레이어(Consensus Layer, CL)와 실행 레이어(Execution Layer, EL)라는 두 프로그램으로 나뉘어 있고 블록을 전파하고 검증하는 모든 과정에서 엔진 API(Engine API)라는 통로로 대화합니다. 지금 이 통로는 JSON-RPC라는 텍스트 방식을 씁니다. 해시, 주소, 트랜잭션, 블롭 같은 이진 데이터를 16진수 문자로 바꿔 보내므로 전송 크기가 두 배로 늘고 양쪽 모두 JSON을 만들고 해석하느라 CPU를 씁니다. 게다가 합의 레이어는 내부에서 SSZ라는 이진 형식을 쓰기 때문에, 엔진 API 경계에서 SSZ를 JSON으로 바꿨다가 다시 내부 형식으로 되돌리는 변환을 반복합니다. 이 EIP는 SSZ 바이트를 그대로 HTTP로 주고받는 전송 방식을 추가해 이런 낭비를 없앱니다. 원문에 따르면 전송 크기가 JSON-RPC 대비 약 50% 줄고, 직렬화가 더 이상 CL과 EL 사이 핵심 경로의 병목이 되지 않습니다.
무엇이 바뀌나
지금
- CL과 EL이 모든 엔진 API 통신을 텍스트 기반 JSON-RPC로 주고받습니다
- 이진 데이터를 16진수 문자열로 바꿔 보내 전송 크기가 두 배가 됩니다
- CL이 SSZ를 JSON으로 바꿨다가 다시 내부 형식으로 되돌리는 변환을 반복합니다
EIP-8178 이후
- SSZ 바이트를 그대로 HTTP REST로 주고받는 전송 방식이 같은 포트에 추가됩니다
- 16진수 인코딩과 JSON 파싱이 사라져 전송 크기가 약 50% 줄어듭니다
- 기존 JSON-RPC는 완전히 유지되어 구현하지 않은 클라이언트는 영향이 없습니다
누구에게 영향이 있나
- 클라이언트 팀: EL과 CL 클라이언트가 새 전송을 구현하는 당사자입니다. 합의 변경이 없는 순수 클라이언트 측 변경이라 하드포크 없이 일반 릴리스로 배포할 수 있습니다.
- 검증자·노드 운영자: 기존 엔진 API 포트(8551)와 같은 JWT 비밀을 그대로 쓰므로 추가 포트나 방화벽 설정이 필요 없습니다. 블록 검증 경로의 직렬화 부담이 줄어듭니다.
- 일반 사용자: 프로토콜 규칙 자체는 바뀌지 않으므로 직접 체감하는 변화는 없습니다. 노드 내부의 통신 효율이 좋아지는 변경입니다.
심층 설명
전송 계층: 같은 포트 위의 REST와 octet-stream
새 전송은 HTTP 위의 자원 중심 REST입니다. 모든 엔드포인트는 기존 엔진 API 포트(기본 8551)의 /engine 접두사 아래에서 제공되고 자원 종류(payloads, forkchoice, blobs)별로 경로가 나뉩니다. 요청과 응답 본문은 Content-Type: application/octet-stream으로 SSZ 직렬화 바이트를 그대로 담고 오류 응답만 text/plain으로 사람이 읽을 수 있는 메시지를 돌려줍니다. 본문이 없는 GET 요청은 Accept: application/octet-stream 헤더를 포함해야 합니다(SHOULD). 인증은 JSON-RPC와 동일한 JWT 방식이며, 모든 요청은 Authorization 헤더에 유효한 JWT 베어러 토큰을 반드시 포함해야 합니다(MUST).
버저닝: JSON-RPC 메서드 버전과 1대 1 대응
엔드포인트는 비컨 API(Beacon API) 관례를 따라 경로에 버전 번호를 넣고 이 번호는 대체하는 JSON-RPC 메서드 버전과 일치합니다. 엔드포인트 요약 기준으로 POST /engine/v4/payloads는 engine_newPayloadV4, GET /engine/v5/payloads/{payload_id}는 engine_getPayloadV5, POST /engine/v3/forkchoice는 engine_forkchoiceUpdatedV3, POST /engine/v3/blobs는 engine_getBlobsV3에 대응합니다. 페이로드 제출은 v1(Paris)부터 v4(Prague), 페이로드 조회는 v1부터 v5(Osaka), 포크초이스는 v1부터 v3(Cancun), 블롭 조회는 v1(Cancun)부터 v3(Osaka), 클라이언트 버전 교환은 v1이 정의됩니다. 새 포크가 새 메서드 버전을 도입하면 새 버전 경로가 추가되고 옛 경로는 폐기할 수 있지만(MAY) 하위 호환을 위해 유지해야 합니다(SHOULD).
HTTP 상태 코드 체계
성공은 두 가지입니다. 200 OK는 SSZ 인코딩된 결과를 본문에 담고 204 No Content는 동기화 중처럼 결과가 null일 때 빈 본문으로 응답합니다. 클라이언트 오류는 400(SSZ 인코딩 손상), 401(JWT 누락이나 무효), 404(알 수 없는 payload ID), 409(잘못된 포크초이스 상태), 413(최대 원소 수 초과), 422(잘못된 페이로드 속성)로 나뉘고 서버 오류는 500(예기치 않은 서버 오류)입니다. 오류 응답 본문은 Content-Type: text/plain의 사람이 읽을 수 있는 메시지입니다.
SSZ 타입 매핑과 null 표현
JSON-RPC의 기본 타입은 SSZ 타입으로 고정 대응됩니다. address는 Bytes20, hash32와 bytes32는 Bytes32, bytes48은 Bytes48, bytes256은 ByteVector[256], uint64와 uint256은 그대로, 가변 길이 bytes는 문맥별 상한을 가진 ByteList[MAX_LENGTH], 배열은 List[T, MAX_LENGTH]입니다. 'T or null'은 List[T, 1]로 표현해 원소 0개면 null(없음), 1개면 값이 있는 것입니다. 이 규칙은 포크초이스 요청의 payload_attributes, PayloadBodiesV1Response의 내부 리스트(모르는 블록은 0개, 아는 블록은 1개), GetBlobsV3Response의 내부 리스트(없는 블롭은 0개, 있는 블롭은 1개)에 쓰입니다.
컨테이너 정의: 모든 포크의 구조체를 SSZ로
엔진 API의 모든 구조체에 대해 포크별 SSZ 컨테이너가 정의됩니다. ExecutionPayloadV1(Paris)은 parent_hash부터 transactions까지의 필드를 담고 V2(Shanghai)는 withdrawals를, V3(Cancun)는 blob_gas_used와 excess_blob_gas를 추가합니다. PayloadStatusV1의 status는 uint8 열거형으로 0=VALID, 1=INVALID, 2=SYNCING, 3=ACCEPTED, 4=INVALID_BLOCK_HASH이고 latest_valid_hash는 값이 없을 때 모두 0으로 채웁니다. ForkchoiceUpdatedResponseV1의 payload_id도 페이로드 빌드를 시작하지 않았으면 모두 0입니다. 블롭 번들은 BlobsBundleV1(블롭당 증명 1개)과 BlobsBundleV2(블롭당 CELLS_PER_EXT_BLOB=128개의 셀 증명)로 나뉘며 GetPayloadResponse는 V2(block_value 추가)부터 V5(BlobsBundleV2와 execution_requests 포함)까지 정의됩니다.
상수와 크기 제한, 보안 요구사항
리스트 상한은 상수로 고정됩니다. 트랜잭션 하나는 최대 MAX_BYTES_PER_TRANSACTION(2**30바이트), 페이로드당 트랜잭션은 MAX_TRANSACTIONS_PER_PAYLOAD(2**20)개, 블록당 블롭 커밋먼트는 MAX_BLOB_COMMITMENTS_PER_BLOCK(4,096)개, 블롭 하나는 BLOB_SIZE(131,072바이트)입니다. 보안 측면에서 SSZ 역직렬화는 JSON 역직렬화와 같은 크기 제한을 반드시 지켜야 하고(MUST), 정의된 최대 크기를 넘는 페이로드는 전체 역직렬화를 시도하기 전에 거부해야 합니다(MUST). 구현은 검증된 SSZ 라이브러리를 쓰고 SSZ 파싱을 광범위하게 퍼즈 테스트해야 하며(SHOULD), URL 경로의 {payload_id}는 처리 전에 올바른 16진수 Bytes8인지 반드시 검증해야 합니다(MUST).
설계 근거: REST, 같은 포트, 하드포크 불필요
원문은 설계 선택의 이유를 밝힙니다. 날것의 TCP 대신 REST를 쓰는 것은 디버깅이 쉽고 로드밸런서, 프록시, 모니터링 같은 기존 인프라를 그대로 쓸 수 있으며 비컨 API가 이미 REST와 SSZ 조합으로 잘 동작하고 있기 때문입니다. CL과 EL 사이 연결은 보통 localhost 통신이라 더 낮은 수준으로 내려갈 실익이 없습니다. 별도 포트 대신 같은 포트를 쓰는 것은 운영자가 포트, 방화벽 규칙, JWT 비밀을 추가로 관리하지 않게 하기 위해서입니다. JSON-RPC는 POST /에 application/json을, SSZ REST는 자원 경로에 application/octet-stream을 쓰므로 둘이 충돌 없이 공존합니다. 이 EIP는 합의 변경, 상태 전이 변경, 새 옵코드가 전혀 없는 순수 클라이언트 측 변경이라 하드포크가 필요 없고 각 클라이언트가 원할 때 일반 릴리스로 배포할 수 있습니다.
진행 상태: Draft
이 EIP의 상태는 Draft입니다. 엔드포인트 구성, 컨테이너 정의, 상수 등 명세 내용이 아직 바뀔 수 있습니다. 기존 JSON-RPC 엔진 API는 완전히 유지되고 항상 사용 가능하므로, 바이너리 SSZ를 구현하지 않은 클라이언트는 영향을 받지 않습니다. 제공된 콜 기록에는 이 EIP에 대한 포크 포함 결정이 없습니다.