ERC-7682 보조 자금 알림 기능 (Auxiliary Funds Capability)
Draft · 계정·지갑 · 2024-04-09 작성
지갑이 온체인 잔액 외에 쓸 수 있는 추가 자금이 있다는 사실을 앱에 알리는 기능입니다. 앱은 잔액 부족을 이유로 사용자를 막지 않을 수 있습니다.
왜 필요한가
많은 앱은 어떤 동작을 허용하기 전에 사용자의 주소에 있는 온체인 잔액을 확인합니다. 예를 들어 탈중앙 거래소(dex)에서 토큰을 바꾸려 할 때, 그 주소에 해당 토큰이 모자라면 앱이 거래 자체를 막는 경우가 많습니다. 그런데 일부 지갑은 주소의 온체인 잔액만으로는 보이지 않는 자금에 접근할 수 있습니다. 오프체인 자금을 그 자리에서 온램프(onramp)해 쓰거나, 여러 계정을 관리하는 지갑이 다른 계정의 자산을 필요한 계정으로 옮겨 쓰는 식입니다. 지갑이 이런 추가 자금이 있다는 사실을 앱에 알릴 방법이 없으면, 실제로는 결제할 수 있는 사용자가 잔액 검사에 걸려 불필요하게 차단됩니다. 이 표준은 지갑이 앱에 그 사실을 알리는 공통 방법을 정합니다.
심층 설명
auxiliaryFunds 능력 광고
보조 자금에 접근할 수 있는 지갑은, 그 자금을 쓸 수 있는 각 체인에 대해 wallet_getCapabilities 응답에 auxiliaryFunds 객체를 넣고 supported 필드를 true로 설정해야 합니다(MUST). 선택적으로 assets 필드에 추가 접근 가능한 자산의 주소 배열을 넣을 수 있고 이 배열이 없으면 앱은 지갑이 모든 자산에 추가 접근할 수 있다고 가정해야 합니다(SHOULD). 체인의 네이티브 자산(이더리움의 이더 등)은 EIP-7528에 따라 "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"로 표현해야 합니다. 보조 자금의 출처에는 아무 제약을 두지 않습니다.
requiredAssets 파라미터
지갑이 auxiliaryFunds를 지원하면, 앱은 wallet_sendCalls 요청의 capabilities.auxiliaryFunds 객체에 requiredAssets 파라미터를 넣을 수 있습니다(MAY). 각 항목은 address, amount(자산 최소 단위의 정수를 나타내는 16진수 문자열), standard("erc20", "erc721", "erc1155"), tokenId(ERC-721과 ERC-1155에 필수)로 구성됩니다. 호출 데이터만으로는 실행에 필요한 자산과 수량을 신뢰성 있게 알 수 없으므로, 앱이 명시해 주면 지갑이 자산을 준비, 브리지, 스왑할 수 있습니다. 다만 auxiliaryFunds를 알린 지갑이라도 requiredAssets를 해석하지 못할 수 있으므로 앱은 미지원 상황을 유연하게 처리해야 합니다. 네이티브 자산 요구량은 requiredAssets에 적는 대신 호출의 call.value 필드에서 지갑이 추론해야 합니다(SHOULD).
토큰 표준별 필드 규칙
ERC-20은 amount 필드만 필요하고, ERC-721과 ERC-1155는 amount와 tokenId가 모두 필요합니다. amount의 의미는 표준마다 다릅니다. ERC-20은 최소 단위 수량(소수 18자리 토큰이면 wei), ERC-721은 NFT 개수(단일 NFT는 보통 "0x01"), ERC-1155는 지정한 토큰 ID의 수량입니다. 미래의 토큰 표준은 확장성을 위해 추가 필수 필드를 자산 객체 루트의 속성으로 정의해야 합니다(MUST). 또한 지갑은 requiredAssets의 amount 값을 자산 컨트랙트의 decimal() 값과 교차 확인해 소수 정밀도에 맞게 해석해야 합니다(MUST).
원자적 실행과 오류 코드
브리지, 스왑 같은 보조 자금 준비 과정은 wallet_sendCalls 실행 수명주기와 독립적입니다. atomicRequired 필드는 호출 묶음 실행에만 적용되고 자금 준비에는 적용되지 않습니다. 준비 실패를 위한 오류 코드로 5770(자금 준비 실패, 브리지나 스왑 오류 등), 5771(자산 미지원), 5772(해당 체인에서 더 이상 보조 자금 미지원), 5773(requiredAssets 구조 오류)이 정의됩니다. 자금 준비는 시간이 걸릴 수 있으므로 앱은 wallet_getCallsStatus로 진행 상태를 추적해야 합니다(SHOULD).
앱 구현 지침과 호환성
연결된 지갑이 auxiliaryFunds 능력을 알리면 앱은 자산 잔액 검사를 이유로 사용자의 행동을 막지 말아야 합니다(SHOULD NOT). requiredAssets는 지갑이 auxiliaryFunds 능력을 광고할 때만 포함해야 하며(SHOULD), optional: true로 보내면 이 기능을 지원하는 지갑에는 정보를 주면서 지원하지 않는 지갑과의 호환성도 유지됩니다(SHOULD). 설계 근거로는 보조 잔액을 조회할 URL을 제공하는 대안도 검토했지만 잔액 검사로 막지 말라는 신호로는 불리언 하나면 충분하고 앱의 구현 부담이 가장 적다고 판단했습니다. 이 능력의 형태는 필요하면 더 고급 기능으로 확장할 수 있게 열려 있습니다.
제안 상태
이 제안은 아직 Draft 상태입니다. 내용이 앞으로 바뀔 수 있으므로 구현할 때는 최신 원문을 확인해야 합니다.
쓸 때 주의할 점
- 자금 출처를 가정하지 않기: 앱은 보조 자금의 출처에 대해 어떤 가정도 하지 말아야 합니다(MUST NOT). 앱의 스마트 컨트랙트는 지금처럼 트랜잭션 처리 시 온체인에서 적절한 잔액 검사를 수행해야 합니다.
- 준비 실패에 대비하기: 앱은 지갑이 요구한 자산을 항상 마련할 수 있다고 가정하지 말아야 하며(MUST NOT), 실패를 유연하게 처리해야 합니다(SHOULD).