EIP-8317 컨트랙트 스토리지 레이아웃 서술 형식 (Contract Storage Layout Descriptor Format)

콜 결정 없음 · EVM·실행 · 원문 상태 Draft · 2026-06-25 작성

컨트랙트의 상태 변수가 어느 스토리지 슬롯에 어떻게 저장되는지 기술하는 언어 중립 JSON 형식을 정의합니다. 지갑과 블록 탐색기가 원시 슬롯 변경을 변수 이름과 읽기 쉬운 문장으로 바꿔 보여 줄 수 있게 합니다.

왜 필요한가

블록 탐색기, 디버거, 서명 전에 트랜잭션 결과를 미리 보여 주는 지갑 같은 도구는 원시 스토리지 슬롯 값만 보고는 어떤 변수가 바뀌었는지 알 수 없습니다. 지금은 공통으로 믿고 쓸 형식이 없어서 도구마다 자체 해석 방식을 만들어 씁니다. Solidity 컴파일러의 storageLayout 출력이 사실상 표준처럼 쓰이지만 문제가 있습니다. t_uint256 같은 타입 이름이 Solidity 내부 명명이라 다른 언어가 쓰기 어렵고 공식 문서에서도 실험적이며 바뀔 수 있다고 밝힙니다. 또 네임스페이스 스토리지(ERC-7201)나 다이아몬드 스토리지(ERC-8042)처럼 keccak256 해시로 계산한 슬롯에 구조체를 두는 방식은 컴파일러가 알지 못해 기술할 수 없습니다. 업그레이드 가능한 프록시나 EIP-7702 위임 컨트랙트처럼 레이아웃을 뽑아낼 컴파일러 출력 자체가 없는 경우도 많습니다. 이 형식은 그런 모든 경우를 하나의 예측 가능한 스키마로 담는 것을 목표로 합니다.

무엇이 바뀌나

지금

EIP-8317 이후

누구에게 영향이 있나

심층 설명

파일 구조: compiler, storage, types

레이아웃 파일은 JSON 객체 하나이고 필수 멤버는 compiler, storage, types 세 개입니다. compiler 객체의 language 필드는 "Solidity", "Vyper", "manual"을 지원하며 Huff나 순수 Yul, 수기 어셈블리처럼 컴파일러가 레이아웃의 어떤 부분도 만들지 않은 경우에는 "manual"을 반드시 써야 합니다(MUST). 한 파일 안에서 컴파일러가 배정한 엔트리와 수동으로 정의한 엔트리를 섞을 수 있습니다(MAY). storage는 최상위 스토리지 엔트리의 순서 있는 배열이고 types는 타입 식별자를 타입 정의로 매핑하는 객체입니다. $schema와 $comment는 선택 필드입니다. 원문은 전체 JSON 스키마와 함께 일반 ERC-20, EIP-7702와 ERC-7201 혼합, ERC-8042 다이아몬드의 세 가지 예제 파일을 에셋으로 제공합니다.

스토리지 엔트리와 타입 정의

각 엔트리에는 label(소스 변수 이름), slot(10진수 문자열), offset(슬롯 안 바이트 오프셋, 슬롯 전체를 차지하면 0), type(types 객체를 참조하는 식별자)이 필수입니다. path가 없으면 소비자는 최상위 엔트리부터 구조체 멤버까지 label을 이어붙여 계산해야 합니다(MUST). source는 "compiler"(기본값) 또는 "manual"로, 슬롯과 오프셋이 검증 가능한 소스에서 컴파일러가 낸 것인지 작성자가 직접 선언한 것인지 구분합니다. 타입 정의의 encoding은 inplace, inplace_struct, mapping, dynamic_array, bytes 다섯 가지입니다. 모든 타입은 label과 numberOfBytes를 가지며 mapping은 key와 value를, dynamic_array는 value와 Solidity 출력과의 문자 그대로의 호환을 위한 별칭 base를, inplace_struct는 멤버 엔트리 배열 members를 추가로 가집니다.

baseSlotDerivation: 기준 슬롯을 검증 가능하게

순차 배정이 아닌 방식으로 기준 슬롯을 계산한 엔트리는 baseSlotDerivation 객체로 그 방식을 선언합니다. scheme은 현재 "erc7201", "erc8042", "custom" 세 가지입니다. erc7201이면 소비자가 slot == keccak256(keccak256(namespaceId) - 1) & ~0xff를, erc8042이면 slot == keccak256(namespaceId)를 독립적으로 재계산해 검증할 수 있습니다(MAY). custom은 아직 ERC로 표준화되지 않은 방식을 위한 것으로, formula 필드에 기계 검증이 안 되는 자유 텍스트 설명을 담고 slot은 수동 작성됩니다. 컴파일러가 순차 배정한 슬롯에는 baseSlotDerivation을 쓰면 안 됩니다(MUST NOT). Solidity의 layout at 문법으로 이동한 슬롯도 마찬가지인데, 두 경우 모두 컴파일러가 최종 절대 슬롯을 직접 내보내므로 별도 재유도가 의미 없기 때문입니다.

슬롯 유도 공식과 패킹 변수

복합 타입의 자식 값은 엔트리의 slot을 기준 슬롯으로 삼아 encoding과 compiler.language에 따라 계산한 위치에 저장됩니다. Solidity는 mapping이 keccak256(abi.encode(key, baseSlot)), dynamic_array가 keccak256(baseSlot) + index * elementSlots이고 bytes는 31바이트 이하면 기준 슬롯에 인라인, 넘으면 keccak256(baseSlot)부터 순차 저장합니다. Vyper는 mapping이 0.3.0 이상에서 keccak256(abi.encode(key, baseSlot)), 그 미만에서는 key와 slot 순서가 뒤집힌 keccak256(abi.encode(baseSlot, key))이고 dynamic_array는 baseSlot + 1 + index * elementSlots, bytes는 해시 간접 없이 기준 슬롯부터 인라인입니다. elementSlots = ceil(elementSize / 32)이며 중첩 타입은 단계마다 재귀 적용합니다. 이 표가 이 ERC의 규범적 원천이고 새 언어 지원은 이 ERC의 개정으로만 추가됩니다(MUST). 패킹된 슬롯이 바뀌면 소비자는 slot이 일치하는 각 엔트리를 offset과 numberOfBytes로 검사해 바뀐 변수를 식별해야 하며(MUST) 값이 같은 변수는 표시에서 생략할 수 있습니다(MAY).

display 주석: ERC-7730 어휘로 사람이 읽게

각 엔트리와 구조체 멤버는 선택적 display 객체를 둘 수 있고 어휘는 ERC-7730을 따릅니다. label은 {key[N]}과 {index[N]} 플레이스홀더를 지원하며 바깥쪽이 {key[0]}입니다. keyFormats 배열의 N번째 포매터가 N번째 키나 인덱스에 적용되고 format과 params는 ERC-7730 필드 포매터(tokenAmount, addressName, raw, date 등)와 같은 구조로 저장 값 자체에 적용됩니다. template은 평문 문자열이거나 조건부 항목 배열로, 배열이면 순서대로 평가해 조건이 맞는 첫 항목을 쓰고 조건 없는 항목은 맨 뒤 폴백으로 둡니다(SHOULD). 템플릿은 {label}, {oldValue}, {newValue} 플레이스홀더를 지원합니다. description은 정보 제공용일 뿐이며 추가적인 진위 보장 없이 보안 판단에 의존하면 안 됩니다(MUST NOT). 구조체 멤버가 바뀌면 부모 변수의 해석된 레이블과 멤버 레이블을 함께 표시합니다.

JSON Logic 부분집합

템플릿 조건은 JSON Logic 표현식이지만 이 ERC는 외부 JSON Logic 명세에 의존하지 않고 사용 가능한 부분집합을 직접 규범으로 정의합니다. 표현식은 연산자 하나를 키로 갖는 JSON 객체이고 컨텍스트 변수는 oldValue, newValue, key, index 네 가지입니다. var 연산자는 {"var": "key.0"}처럼 점 구분 경로로 컨텍스트 값을 읽습니다. 필수 지원 연산자는 ==, !=, >, >=, <, <=, !, and, or, var이며(MUST) 지갑은 그 밖의 JSON Logic 연산자나 기능이 있다고 가정하면 안 됩니다(MUST NOT). false, 0, 빈 문자열, 빈 배열, null은 거짓으로, 나머지는 참으로 평가합니다.

신뢰 모델, 범위 제외, 현재 상태

레이아웃 파일 자체가 공격면이 될 수 있습니다. slot의 type이나 path를 거짓으로 기술한 파일은 실제 저장 변경에 대해 오해를 부르는 변수 이름이나 값을 보여 주게 만들 수 있습니다. 이 ERC는 레이아웃 파일의 신뢰와 배포 메커니즘을 정의하지 않으며 이 형식을 참조하는 ERC-7730 같은 표준이 보안 관련 표시에 쓰기 전에 파일의 진위를 어떻게 확립할지 정할 책임을 집니다. 한편 트랜지언트 스토리지는 트랜잭션이 끝나면 지워져 결과에 영향이 없으므로 범위 밖입니다. 이 문서의 상태는 Draft이므로 필드 구성과 세부 규칙은 아직 바뀔 수 있고 코어 개발자 콜의 포함 결정 같은 기록은 현재 없습니다.

EIP 원문 · ← EIPs