ERC-7946 단방향 지갑 업링크(UWULink) (Unidirectional Wallet Uplink aka UWULink)
Draft · 계정·지갑 · 2025-05-10 작성
dApp이 지갑과 연결하거나 사용자 주소를 공개하지 않고도 QR코드나 NFC로 여러 컨트랙트 호출을 하나의 트랜잭션으로 묶어 요청할 수 있게 하는 단방향 통신 표준입니다.
왜 필요한가
기존에는 dApp이 지갑과 상호작용하려면 먼저 연결(eth_requestAccounts 등)을 맺어 사용자 주소를 알아야 했고 토큰 승인과 스왑처럼 여러 단계가 필요한 작업은 매번 따로 서명해야 했습니다. WalletConnect 같은 세션 기반 연결은 중계 서버를 거치며 무겁고 1회성 상호작용에는 과도합니다. 또 EIP-681 같은 기존 URI 방식은 16진수로 주소와 콜데이터를 표현해 QR코드에 담기엔 용량이 금방 커집니다. 이 때문에 사용자는 매번 지갑을 노출하고 여러 번 승인해야 했고 포스터나 포스 단말처럼 연결이 불가능한 오프라인 상황에서는 복잡한 트랜잭션을 요청할 방법이 없었습니다.
구현해야 하는 것
message UWULinkRequest { uint64 chain_id = 1; // EIP-155 chain ID for the target chain oneof request_type { Batch batch = 2; ResolverReference resolver = 3; } }: 요청 전체를 감싸는 최상위 메시지로, 대상 체인 ID와 정적 배치 또는 리졸버 참조 중 하나를 담습니다.message Batch { repeated Call calls = 1; }: 정적 모드에서 실행할 호출 목록을 담는 메시지입니다.message Call { bytes to = 1; // 20-byte address of target contract optional bytes value = 2; // (optional) up to 32-byte big-endian ETH value optional bytes data = 3; // (optional) calldata for the call }: 대상 주소, ETH 값, 콜데이터로 이루어진 개별 컨트랙트 호출을 정의합니다.message ResolverReference { bytes resolver_address = 1; // 20-byte address of resolver contract bytes resolver_data = 2; // opaque data to pass to resolver }: 프로그래밍 모드에서 호출 목록을 생성할 리졸버 컨트랙트 주소와 전달 데이터를 담습니다.function getCalls(address requester, bytes calldata data) external returns (Call[] memory calls);: 요청자 주소와 데이터를 받아 실행할 호출 배열을 계산해 반환합니다.function getErrorCodeDetails(uint256 errorCode) external returns (string memory information);: 에러 코드에 대한 설명 문자열을 반환합니다. 사용자에게 보여주기보다 개발자 확인용입니다.error CallGenerationFailure(uint256 errorCode);: 호출 목록 생성에 실패했을 때 리졸버별 에러 코드와 함께 발생시키는 에러입니다.
심층 설명
단방향 통신 구조
UWULink는 dApp에서 지갑으로만 정보가 흐르는 단방향 프로토콜입니다. 지갑은 요청을 받아 처리할 뿐 dApp에 어떤 데이터도 되돌려 보내지 않습니다. 핸드셰이크나 연결 세션이 없어 dApp은 사용자의 주소나 지갑 종류를 전혀 알 수 없습니다. 요청은 QR코드 스캔이나 NFC 태그처럼 사용자가 스스로 가져오는 방식으로만 전달되며 지갑은 요청이 잘못되었거나 지원하지 않으면 사용자에게 알리고 거부하면 됩니다.
바이너리 인코딩과 URI 스킴
요청은 Protocol Buffers v3 스키마로 직렬화된 뒤 base64로 인코딩되어 uwulink:<base64> 형태의 URI로 전달됩니다. QR/NFC처럼 용량이 제한된 채널에서 16진수 기반의 기존 방식(EIP-681)보다 훨씬 압축된 표현이 가능합니다. base64 출력을 URI에 넣을 때는 +, / 같은 문자를 퍼센트 인코딩하거나 URL-safe base64 변형을 쓸 수 있으며 디코딩 후 데이터는 항상 정해진 protobuf 스키마와 일치해야 합니다.
정적 모드: Batch와 Call
정적 모드에서는 요청 안에 실행할 호출 목록(Batch)이 그대로 담깁니다. 각 Call은 대상 주소(to, 20바이트), 선택적인 ETH 값(value, 최대 32바이트 빅엔디언, 앞의 0은 생략), 선택적인 콜데이터(data)로 구성됩니다. 지갑은 to와 resolver_address가 정확히 20바이트가 아니면 메시지를 거부해야 하며 value가 비어 있으면 0으로 해석합니다.
프로그래밍 모드와 UWUResolver 인터페이스
프로그래밍 모드에서는 호출 목록 대신 리졸버 컨트랙트 주소와 resolver_data만 담깁니다. 지갑은 from=address(0)으로 resolver_address의 getCalls(requester, data)를 eth_call로 실행해 호출 배열을 받아옵니다. requester에는 지갑 자신의 주소를 넣어 리졸버가 사용자별로 다른 결과를 만들 수 있게 하되, 이 주소는 dApp이 아니라 지갑이 쓰는 RPC 서버에만 노출됩니다. 호출이 실패하면 지갑은 반드시 요청을 중단하고 사용자에게 생성 실패를 알려야 합니다. 받은 호출은 정적 모드와 똑같이 사용자에게 보여주고 승인받습니다.
원자적 실행과 체인 식별
요청에 담긴 모든 호출은 반드시 원자적으로 실행됩니다. 하나라도 되돌려지면 전체 배치가 되돌려집니다. 요청에는 chain_id가 포함되어 지갑이 대상 체인을 확인하거나 전환하는 데 쓰입니다. 지갑이 해당 체인을 지원하지 않으면 요청을 거부해야 합니다. 이는 EIP-681 URI의 chainId 처리와 비슷한 방식입니다.
하위 호환성
UWULink는 추가적인(additive) 프로토콜로 기존 표준을 깨지 않습니다. uwulink: 스킴을 모르는 지갑은 그냥 무시하거나 오류를 표시하면 되고 EIP-681 QR코드와 혼동될 위험도 없습니다. Proto3 규칙상 수신자는 모르는 필드를 무시하므로, 향후 expiration_timestamp나 origin 같은 선택 필드를 추가해도 기존 지갑은 핵심 요청을 그대로 처리할 수 있습니다. dApp은 UWULink와 기존 지갑 연결 방식을 동시에 제공할 수 있습니다.
제안 상태
이 ERC는 현재 Draft 상태입니다. Rationale 섹션과 참조 구현은 아직 작성되지 않았고 예시로 든 인코딩 값도 실제가 아닌 개념 설명용입니다. 따라서 메시지 스키마나 리졸버 인터페이스는 앞으로 바뀌거나 논의가 멈출 수 있습니다.
쓸 때 주의할 점
- 피싱성 QR/NFC 요청: 악의적인 주체가 그럴듯한 UWULink QR코드를 제시해 사용자가 그대로 승인하면 자금 전송이나 토큰 승인이 일어날 수 있습니다. 지갑은 알려진 주소의 이름이나 ENS, 함수 시그니처, 값의 크기 등을 사람이 읽을 수 있게 보여주어야 합니다.
- 리졸버 컨트랙트에 대한 신뢰: 프로그래밍 모드에서는 사용자가 리졸버 컨트랙트가 만든 호출을 신뢰하게 됩니다. 지갑은 리졸버가 반환한 호출도 정적 모드와 똑같이 사용자에게 보여주어야 합니다. 악성 리졸버는 입력과 무관하게 사용자의 ETH 전부를 공격자에게 보내는 호출을 반환할 수 있습니다.
- 항상 되돌려지는 요청으로 인한 가스 낭비: 지갑은 가능하면 배치를 사전에 시뮬레이션해 되돌림을 미리 감지해야 합니다. 호환되지 않는 호출을 포함시켜 항상 되돌려지는 배치를 만들면 사용자가 가스비를 낭비할 수 있습니다.
- 거대한 페이로드로 인한 서비스 거부: 지갑은 크기 제한을 두고 리졸버 호출에 공급하는 가스도 제한해야 합니다. 지나치게 큰 UWULink 페이로드나 리졸버가 반환하는 과도하게 큰 결과는 지갑 앱을 멈추게 할 수 있습니다.
- 출처를 알 수 없는 요청: 사용자가 하드웨어 지갑을 쓸 때처럼 매 요청을 스스로 검토하고 신뢰해야 합니다. QR/NFC로 전달되는 요청에는 도메인 같은 출처 정보가 없어 지갑이 화이트리스트나 블랙리스트를 적용할 수 없습니다.