ERC-7769 ERC-4337용 JSON-RPC API (JSON-RPC API for ERC-4337)
Draft · 계정·지갑 · 2024-08-23 작성
스마트 계정 지갑이 ERC-4337 번들러와 통신하는 공통 JSON-RPC 메서드를 정의합니다. 일반 트랜잭션처럼 UserOperation을 제출하고 가스를 추정하고 결과를 조회할 수 있게 합니다.
왜 필요한가
ERC-4337 계정 추상화에서는 사용자의 요청이 일반 이더리움 트랜잭션이 아니라 UserOperation이라는 별도 객체로 표현됩니다. 그런데 기존 이더리움 JSON-RPC 메서드는 트랜잭션을 다루도록 만들어져 있어 UserOperation 객체를 보내거나 조회하는 데에는 맞지 않습니다. 공통 규격이 없으면 지갑과 앱은 번들러 구현마다 다른 방식으로 연동해야 하고 별도의 UserOperation 멤풀을 여러 구현이 함께 운영하기도 어렵습니다. 이 표준은 트랜잭션에 있던 제출, 가스 추정, 조회 기능을 UserOperation에 맞게 다시 정의해 모든 ERC-4337 구현이 같은 API를 서로 바꿔 쓸 수 있게 합니다. 또한 개발과 테스트, 디버깅을 돕는 debug 메서드 집합도 함께 정의합니다.
구현해야 하는 것
eth_sendUserOperation: UserOperation을 검증해 멤풀에 제출합니다. 성공하면 userOpHash를, 실패하면 오류 코드와 사유를 반환합니다.eth_estimateUserOperationGas: 서명 검증 없이 UserOperation 실행에 필요한 가스 한도들을 추정해 돌려줍니다.eth_getUserOperationByHash: userOpHash로 UserOperation과 포함된 블록, 트랜잭션 정보를 조회합니다.eth_getUserOperationReceipt: UserOperation의 성공 여부와 실제 가스 비용이 담긴 영수증을 조회합니다.eth_supportedEntryPoints: 클라이언트가 지원하는 EntryPoint 컨트랙트 주소 배열을 반환합니다. 첫 요소가 선호하는 주소입니다.eth_chainId: EIP-155 체인 ID를 반환합니다.debug_bundler_clearState: 번들러의 멤풀과 평판 데이터를 비웁니다. 테스트 전용입니다.debug_bundler_dumpMempool: 현재 멤풀에 있는 UserOperation 배열을 반환합니다.debug_bundler_sendBundleNow: 즉시 번들을 만들어 handleOps 트랜잭션으로 실행하고 트랜잭션 해시를 반환합니다.debug_bundler_setBundlingMode: 번들링 방식을 manual 또는 auto로 설정합니다.debug_bundler_setReputation: 주어진 주소들의 평판 값을 설정합니다.debug_bundler_dumpReputation: 관측된 모든 주소의 평판 데이터를 반환합니다.debug_bundler_addUserOps: 검증을 건너뛰고 UserOperation 배열을 멤풀에 직접 넣습니다.
심층 설명
번들러의 역할
번들러(bundler)는 이 표준의 API를 노출하는 노드입니다. 하나 이상의 UserOperation을 모아 번들로 만들고 이를 EntryPoint 컨트랙트의 handleOps 호출 한 번으로 네트워크에 제출합니다. 지갑은 트랜잭션을 직접 보내는 대신 이 API로 번들러에 UserOperation을 전달하고 실제 온체인 실행은 번들러가 대신 수행합니다.
eth_sendUserOperation의 검증 규칙
클라이언트는 받은 UserOperation을 반드시 검증해야 하며 시뮬레이션을 통과해 풀에 수락된 경우에만 userOpHash를 반환해야 합니다. 실패하면 userOpHash 대신 실패 사유를 반환해야 합니다. 모든 필드는 16진수 값으로 설정해야 하고 빈 bytes는 "0x"로 적어야 합니다. factory와 factoryData는 둘 다 주거나 둘 다 생략해야 하며 paymaster, paymasterData, paymasterValidationGasLimit, paymasterPostOpGasLimit 네 필드도 전부 주거나 전부 생략해야 합니다. entryPoint 주소는 supportedEntryPoints 호출이 반환하는 목록 중 하나여야 합니다.
표준 오류 코드
실패 시 code와 message를 담은 error 객체를 반환합니다. -32602는 UserOperation 구조나 필드가 잘못된 경우입니다. -32500은 EntryPoint의 simulateValidation이 거부한 경우로 message에 FailedOp 이벤트의 AAxx 오류 메시지를 담아야 합니다. -32501은 paymaster의 validatePaymasterUserOp이 거부한 경우로 data에 paymaster 값을 담아야 합니다. -32502는 ERC-7562 opcode 검증 규칙 위반, -32503은 validUntil과 validAfter의 유효 시간 범위를 벗어난 경우, -32504는 평판 규칙에 따라 paymaster가 제한(throttled)되거나 차단(banned)된 경우, -32505는 paymaster의 스테이크나 언스테이크 지연이 너무 낮은 경우입니다. -32507은 지갑 서명 검증 실패, -32508은 paymaster 잔액이 대기 중인 UserOperation 전부를 감당하지 못하는 경우입니다.
EIP-7702 위임 계정 지원
EIP-7702가 활성화된 네트워크에서는 UserOperation에 eip7702Auth 튜플을 넣을 수 있습니다. 이 튜플은 위임 주소를 바꿀 때만 필요하고 한 번 온체인에 저장되면 이후 UserOperation에는 다시 넣지 않아도 됩니다. EIP-7702로 위임된 sender를 쓸 때는 factory 필드를 INITCODE_EIP7702_MARKER = 0x7702 플래그로 설정해야 하며 이때 factoryData는 factory가 아니라 sender 컨트랙트로 직접 전달됩니다. 이 호출은 validateUserOp 전에 별도로 이뤄지므로 검증 중에 sender가 두 번 호출됩니다. factoryData를 비워 두면 호출이 생략됩니다. 이 호출의 목적은 sender 컨트랙트가 validateUserOp으로 UserOperation을 받아들이기 전에 스토리지를 초기화할 기회를 주는 것입니다.
가스 추정 방식
eth_estimateUserOperationGas는 가스 한도와 가스 가격이 없는 UserOperation을 받아 필요한 가스 값을 돌려줍니다. signature 필드는 무시되므로 사용자 승인이 필요 없지만 올바른 길이의 스텁(stub) 서명을 넣어야 할 수 있습니다. maxFeePerGas와 maxPriorityFeePerGas는 기본값이 0이어서 계정이나 paymaster의 지불이 요구되지 않습니다. eth_call과 동일한 State Override Set도 선택적으로 받습니다. 반환값은 preVerificationGas, verificationGasLimit, callGasLimit이고 paymaster 주소를 지정한 경우에만 paymasterVerificationGasLimit을 추가로 돌려줍니다. 실제 postOpGasLimit은 신뢰성 있게 추정할 수 없으므로 paymaster가 계정에 값을 제시하고 온체인 검증에서 그 값을 요구해야 합니다. 계정의 내부 호출이나 paymaster의 postOp 호출이 되돌려지면 오류를 반환할 수 있습니다.
조회 메서드와 영수증
eth_getUserOperationByHash는 userOpHash로 UserOperation을 조회합니다. 블록에 포함됐으면 entryPoint, blockNumber, blockHash, transactionHash를 덧붙인 전체 객체를 반환합니다. 멤풀에 대기 중이면 null 또는 블록 관련 값이 null인 객체를 반환할 수 있으며 둘 다 아니면 null을 반환합니다. eth_getUserOperationReceipt는 userOpHash, entryPoint, sender, nonce, paymaster와 함께 actualGasCost(계정이나 paymaster가 실제 지불한 금액), actualGasUsed(사전 검증, 생성, 검증, 실행을 포함한 총 가스), success(되돌림 없이 완료됐는지), reason(되돌림 사유), logs를 담습니다. logs에는 같은 번들의 다른 UserOperation 로그가 포함되지 않지만 함께 담기는 receipt의 TransactionReceipt는 이 UserOperation만이 아니라 번들 전체에 대한 것입니다.
debug 네임스페이스와 테스트 스위트
debug_bundler_* 메서드는 테스트 모드에서만 제공해야 하며 호환성 테스트 스위트가 요구합니다. clearState는 멤풀과 paymaster, 계정, factory의 평판 데이터를 비웁니다. dumpMempool은 현재 멤풀을 덤프하며 sendBundleNow는 즉시 번들을 만들어 handleOps 트랜잭션으로 실행합니다. setBundlingMode로 manual 모드를 설정하면 번들을 보내기 위해 sendBundleNow를 명시적으로 호출해야 합니다. setReputation과 dumpReputation은 주소별 평판(opsSeen, opsIncluded, status)을 설정하고 조회하며 addUserOps는 검증을 건너뛰고 UserOperation들을 멤풀에 직접 주입합니다. debug 함수를 명시적으로 요구하는 이유는 번들러 명세 테스트 스위트로 구현의 규격 준수를 검증하기 위해서입니다.
호환성과 제안 상태
이 표준은 새로운 JSON-RPC API를 정의할 뿐이므로 원문은 하위 호환성 문제가 없다고 밝힙니다. 다만 이 제안은 아직 Draft(초안) 상태라서 앞으로 내용이 바뀔 수 있습니다. 구현하거나 연동할 때는 최신 원문을 확인하는 것이 안전합니다.
쓸 때 주의할 점
- UserOperation 멤풀에 대한 DoS 공격 방지: 공개 ERC-4337 노드 운영은 계산량이 많은 작업이라 서비스 거부(DoS) 공격의 표적이 될 수 있습니다. ERC-7562 검증 규칙이 참여자의 평판을 추적하고 악의적으로 만든 UserOperation을 받지 않도록 하는 방법을 정의해 이를 해결합니다. 모든 ERC-4337 노드가 DoS 위험을 줄이기 위해 ERC-7562 검증 규칙을 함께 구현할 것을 강하게 권고합니다.
- 프로덕션에서 debug API 차단: debug 네임스페이스의 API는 공개적으로 제공될 용도가 아닙니다. 프로덕션 구현은 이를 기본으로 활성화해서는 안 되며 활성화할 경우 이 API를 노출했을 때의 잠재적 위험을 알리는 명확한 경고를 띄워야 합니다.