ERC-8119 매개변수 저장 키 형식 (Parameterized Storage Keys)

Draft · 기타 · 2025-01-06 작성

스마트 컨트랙트의 키-값 저장에서 registration/1, user[alice]처럼 키에 매개변수를 붙이는 공통 문자열 형식을 정합니다. 구현마다 제각각이던 키 표기법을 하나로 맞춥니다.

왜 필요한가

이더리움 스마트 컨트랙트는 메타데이터를 저장할 때 문자열 키와 값을 짝지어 두는 키-값 저장(key-value storage)을 자주 씁니다. 그런데 같은 종류의 메타데이터가 여러 개 있을 때, 예를 들어 등록 기록 1번, 2번, 3번을 따로 저장하려면 키 이름에 번호 같은 매개변수를 붙여야 합니다. 지금까지는 매개변수를 붙이는 방식이 표준으로 정해져 있지 않아 구현마다 제각각이었습니다. 어떤 프로젝트는 하이픈을 쓰고 어떤 프로젝트는 다른 구분자를 쓰는 식이면, 한 앱이 저장한 키를 다른 앱이 읽으려 할 때 해석 규칙이 달라 상호 운용이 깨지고 키를 기계적으로 나누어 읽는 파싱(parsing)도 어려워집니다. 이 표준은 매개변수가 붙은 문자열 키의 공통 형식을 정해 이런 혼란을 줄이려 합니다.

심층 설명

두 가지 인코딩

매개변수가 있는 키는 두 형식 중 정확히 하나를 써야 합니다. 첫째는 슬래시/콜론 형식으로 <key-label>/<key-parameter> 또는 <key-label>:<key-parameter>이며 매개변수는 정확히 하나입니다. 둘째는 대괄호 형식으로 <key-label>[<key-parameter-1>][<key-parameter-2>]...이며 매개변수를 하나 이상 붙일 수 있습니다. 두 형식을 한 키에 섞는 것은 허용되지 않습니다. 예를 들어 key/param[extra]는 잘못된 형식입니다.

key-label 문자 규칙

key-label은 출력 가능한 ASCII 문자만 쓸 수 있고 그중에서도 공백, 슬래시(/), 콜론(:), 왼쪽 대괄호([)는 제외됩니다. 허용 코드 포인트는 0x21-0x2E, 0x30-0x39, 0x3B-0x5A, 0x5C-0x7E이며, 제어 문자(0x00-0x1F), 공백(0x20), 슬래시(0x2F), 콜론(0x3A), 왼쪽 대괄호(0x5B), DEL(0x7F)은 명시적으로 제외됩니다. 이 네 문자를 레이블에서 빼 둔 덕분에 두 인코딩 모두 모호함 없이 파싱할 수 있습니다. %gain/50, $price/100, #tag/featured처럼 퍼센트, 달러, 해시 같은 특수문자는 레이블에 쓸 수 있습니다.

슬래시/콜론 형식의 파싱 규칙

파싱은 문자열에서 /나 : 중 먼저 나오는 것을 구분자로 삼고 그 뒤의 모든 문자를 하나의 매개변수로 봅니다. 그래서 website/http://website.com이나 key/value/with/slashes처럼 매개변수 안에 /나 :가 더 들어 있어도 문제가 없습니다. 매개변수는 UTF-8 문자열이면 되므로 name/María, description/说明, title/タイトル 같은 키도 유효합니다. 단, 구분자 바로 뒤 문자는 공백이면 안 됩니다. key/ value는 잘못된 형식이고 key/hello world처럼 공백이 중간에 오는 것은 허용됩니다. 공백으로 시작하는 데이터가 꼭 필요하면 따옴표 안 첫 문자로 공백을 넣는 인용 인코딩을 씁니다.

대괄호 형식의 파싱 규칙

파서는 첫 [ 직전까지를 레이블로 읽고 이어서 대괄호로 감싼 매개변수를 순서대로 하나 이상 읽습니다. 각 매개변수는 닫는 구분자로 예약된 ]를 제외한 어떤 UTF-8 문자열도 될 수 있으며 title[说明][日本語]처럼 UTF-8 매개변수도 가능합니다. 마지막 ] 뒤에는 어떤 문자도 올 수 없습니다. 따라서 key[label처럼 괄호가 닫히지 않거나 key[]tail처럼 괄호 뒤에 글자가 남으면 잘못된 형식입니다. 대괄호 형식은 여러 매개변수를 문자열 하나 안에 따로 인코딩하지 않고도 명시적인 구조로 표현하기 위해 추가되었습니다.

구분자를 이렇게 고른 이유

슬래시와 콜론은 프로그램으로 파싱하기 쉬운 명확한 구분자이고 둘 중 먼저 나오는 것을 쓰는 규칙 덕분에 파싱 규칙이 하나로 유지되며 매개변수 안에 두 문자가 다시 나와도 됩니다. 또 짧고 읽기 좋아 긴 텍스트 값에도 어울리고 끝에 ]를 붙일 필요가 없습니다. 레이블에서 /, :, [를 제외해도 레이블은 원래 ASCII 위주로 쓰이므로 큰 제약이 아니며 구분자 바로 뒤 공백을 금지한 것은 파싱을 단순하게 하고 모호함을 피하기 위해서입니다.

적용 범위와 하위 호환

이 형식은 Solidity의 mapping(string => bytes), Vyper의 해시 맵 등 문자열 키 저장을 지원하는 모든 EVM 호환 언어에 적용됩니다. 참조 구현은 registration/1, registration/2, registration/3 키로 값을 저장하고 다시 읽어 오는 Solidity 컨트랙트를 보여 줍니다. 이 ERC는 완전히 하위 호환됩니다. 매개변수 키를 쓰지 않는 기존 구현은 영향을 받지 않고 비표준 형식을 쓰는 구현도 계속 동작하지만 상호 운용성을 위해 이 형식으로 옮기도록 권장됩니다.

초안 단계의 제안

이 ERC는 2025년 1월 6일에 만들어진 초안(Draft) 상태입니다. 논의 과정에서 형식 규칙이 바뀌거나 제안이 멈출 수 있으므로, 구현하기 전에 최신 원문을 확인하는 것이 좋습니다.

쓸 때 주의할 점

ERC 원문 · ← ERCs