ERC-8110 다이아몬드 도메인 스토리지 구조 (Domain Architecture for Diamonds)

Draft · 기타 · 2025-12-20 작성

다이아몬드(Diamond) 패턴 컨트랙트의 저장소를 파셋이 아니라 역할별 도메인 단위로 나눠 이름 짓고 관리하는 구조 규칙을 정의합니다. 이를 통해 저장소 충돌과 업그레이드 실수를 줄입니다.

왜 필요한가

ERC-2535 다이아몬드 표준은 파셋을 통한 모듈화를 제공하지만 저장소를 어떻게 구성할지는 정해두지 않았습니다. 그래서 팀마다 저장소 구조가 제각각이고, 저장소 식별자가 파셋 사이에서 일관되게 검증되거나 재사용되지 않아 예상치 못한 충돌이나 업그레이드 시 상태 오염이 생길 수 있습니다. ERC-8042가 사람이 읽을 수 있는 저장소 식별자를 도입했지만, 큰 프로젝트에서 그 식별자들을 어떻게 구조화하고 묶을지는 정의하지 않았습니다. 공통된 구조 없이는 도구화와 감사가 어렵고, 어떤 파셋이 어떤 상태를 실제로 소유하는지 불분명해 유지보수 위험이 커집니다.

구현해야 하는 것

심층 설명

도메인 정의

도메인은 저장공간의 개념적 소유 단위입니다. 도메인 하나는 저장소 구조체 하나, 식별자 하나와 정확히 대응합니다. 여러 함수 셀렉터가 하나의 도메인을 함께 읽거나 쓸 수 있고, 도메인은 파셋과 독립적이어서 여러 파셋이 같은 도메인을 다룰 수 있습니다(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 상태로, 아직 확정되지 않았고 앞으로 내용이 바뀌거나 중단될 수 있는 제안입니다.

쓸 때 주의할 점

ERC 원문 · ← ERCs