ERC-8110 다이아몬드 도메인 스토리지 구조 (Domain Architecture for Diamonds)
Draft · 기타 · 2025-12-20 작성
다이아몬드(Diamond) 패턴 컨트랙트의 저장소를 파셋이 아니라 역할별 도메인 단위로 나눠 이름 짓고 관리하는 구조 규칙을 정의합니다. 이를 통해 저장소 충돌과 업그레이드 실수를 줄입니다.
왜 필요한가
ERC-2535 다이아몬드 표준은 파셋을 통한 모듈화를 제공하지만 저장소를 어떻게 구성할지는 정해두지 않았습니다. 그래서 팀마다 저장소 구조가 제각각이고, 저장소 식별자가 파셋 사이에서 일관되게 검증되거나 재사용되지 않아 예상치 못한 충돌이나 업그레이드 시 상태 오염이 생길 수 있습니다. ERC-8042가 사람이 읽을 수 있는 저장소 식별자를 도입했지만, 큰 프로젝트에서 그 식별자들을 어떻게 구조화하고 묶을지는 정의하지 않았습니다. 공통된 구조 없이는 도구화와 감사가 어렵고, 어떤 파셋이 어떤 상태를 실제로 소유하는지 불분명해 유지보수 위험이 커집니다.
구현해야 하는 것
function equipmentStorage() pure returns (EquipmentStorage storage s): 장비(Equipment) 도메인 전용 저장소 슬롯의 위치를 반환합니다.function characterStorage() pure returns (CharacterStorage storage s): 캐릭터 도메인의 메인 저장소 슬롯 위치를 반환합니다.function characterMountedStorage() pure returns (CharacterMountedStorage storage s): 캐릭터 도메인의 서브도메인인 탑승 상태 저장소 슬롯 위치를 반환합니다.function gameSettingsStorage() pure returns (GameSettingStorage storage s): 여러 파셋이 공유하는 게임 전역 설정 저장소 슬롯 위치를 반환합니다.
심층 설명
도메인 정의
도메인은 저장공간의 개념적 소유 단위입니다. 도메인 하나는 저장소 구조체 하나, 식별자 하나와 정확히 대응합니다. 여러 함수 셀렉터가 하나의 도메인을 함께 읽거나 쓸 수 있고, 도메인은 파셋과 독립적이어서 여러 파셋이 같은 도메인을 다룰 수 있습니다(MAY). 도메인은 파셋 이름이 아니라 비즈니스나 시스템 책임에 따라 정의해야 합니다(SHOULD).
식별자 명명 규칙
저장소 식별자는 keccak256 해시로 저장 위치를 정하는, 사람이 읽을 수 있는 문자열입니다. 최소 형식은 {project}.{domain-name}.{version}이고, 확장 형식은 {org}.{project}.{domain-type}.{domain-name}.{version}입니다. domain-type은 diamond(핵심 다이아몬드 프로토콜), system(재진입 방지·일시정지·접근제어 같은 공유 기능), business(토큰·가드·모듈 같은 앱 특화 기능) 중 하나를 권장합니다(SHOULD). version을 생략하면 v1을 뜻하며, 레이아웃이 더 이상 append-only가 아닌 변경이 있을 때만 올려야 합니다(MUST).
도메인 구조체 규칙
각 도메인은 저장소 구조체와 식별자를 정확히 하나씩 가져야 하고(MUST), 도메인 이름을 딴 전용 디렉터리에 구현하는 것이 권장됩니다(SHOULD). 구조체에 필드를 추가할 때는 항상 끝에만 추가해야 하며(MUST) append-only 상태를 유지해야 합니다.
서브도메인
서브도메인은 기존 도메인에 속하면서도 저장소가 격리된 수직 확장입니다. 식별자는 {project}.{domain-name}.{version}.{sub-domain} 형식이고, 버전은 서브도메인이 도입된 시점의 부모 도메인 버전을 가리킬 뿐 독립적인 버전 체계는 아닙니다. 서브도메인은 자신만의 ERC-8042 식별자와 저장소 레이아웃을 가져야 하고(MUST), 부모 도메인의 저장소를 수정하거나 덧붙이면 안 되며(MUST NOT), 항상 부모 도메인에 종속된 개념으로 남아야 합니다(MUST).
저장소 선언 요건
각 도메인의 저장소 구조체는 ERC-8042의 NatSpec 주석인 ///@custom:storage-location erc8042:<NAMESPACE_ID>로 반드시 표시해야 합니다(MUST). 이 표준 자체는 저장 위치 계산 공식을 새로 정의하지 않으며, 이 주석을 통해 도메인 저장소를 도구가 자동으로 찾아내고 모호함 없이 식별할 수 있게 하는 데 목적이 있습니다.
디렉터리 규칙
디렉터리 구조는 도메인 소유권을 반영해야 합니다(SHOULD). 각 도메인은 저장소 소유를 위한 논리적 네임스페이스이고 디렉터리는 그 물리적 표현입니다. 파셋은 로직 컨테이너일 뿐 저장소를 소유하지 않으며 도메인 디렉터리 옆이나 안에 위치할 수 있습니다(MAY). 디렉터리 이름과 저장소 식별자가 모두 도메인 정보를 담아야 도구와 정적분석이 셀렉터, 도메인, 저장소 레이아웃을 자동으로 연결할 수 있습니다.
업그레이드 시나리오
업그레이드는 파셋이 아니라 새 셀렉터가 도메인과 저장소에 미치는 영향으로 분류합니다. Case 1은 새 저장소가 필요 없는 경우로 기존 파셋이나 도메인에 그대로 추가합니다. Case 2는 기존 도메인에 속하지 않는 상태가 생기는 수평 업그레이드로 새 도메인과 식별자, 저장소를 만들어야 합니다(MUST). Case 3은 기존 도메인에 속하는 새 변수가 필요한 수직 업그레이드로, 기존 구조체 끝에 필드를 추가하는 방법(옵션 A)과 서브도메인을 새로 만드는 방법(옵션 B) 중 선택할 수 있습니다(MAY). Case 4는 레이아웃이 깨지는 변경으로, 새로 버전이 붙은 식별자와 레이아웃을 만들어야 하며(MUST) 데이터 마이그레이션은 프로젝트가 직접 처리해야 합니다(MUST).
제안 상태
이 표준은 현재 Draft 상태로, 아직 확정되지 않았고 앞으로 내용이 바뀌거나 중단될 수 있는 제안입니다.
쓸 때 주의할 점
- 저장소 충돌 감소: 도메인별로 명시적이고 결정적인 저장소 식별자를 쓰면 서로 관련 없는 파셋이나 업그레이드 사이의 저장소 충돌 위험이 줄어듭니다.
- 식별자 재사용에 따른 실수 방지: 일관된 명명 규칙을 강제하면 식별자를 일관성 없이 쓰거나 재사용해서 생기는 사람의 실수를 줄일 수 있습니다.
- append-only 레이아웃과 상태 보존: 각 도메인이 자신의 ERC-8042 식별자를 소유하고 저장소 레이아웃을 append-only로만 확장하면, 기존 상태를 건드리지 않고 저장소를 안전하게 진화시킬 수 있습니다.