이더리움 트랜잭션 영수증 완벽 정리: 상태·가스·로그 읽는 법

컨트랙트 거래를 보낸 뒤 지갑의 표시가 ‘대기 중’에서 ‘확인됨’으로 바뀌고, 블록 탐색기에는 초록색 체크가 나타납니다. 이 판정은 어디서 왔을까요? 핵심은 이더리움 **트랜잭션 영수증(Transaction Receipt)**이에요. 영수증은 블록체인 기초와 실행 상태·수수료·이벤트 데이터를 연결하는 압축된 결과표입니다. 다만 거래가 공정했다거나 토큰이 진짜라는 보증서는 아니에요.

이 글에서는 영수증이 무엇을 기록하는지, eth_getTransactionReceipt로 어떻게 읽는지, gasUsed와 cumulativeGasUsed가 왜 다른지, 그리고 영수증이 증명하지 못하는 것까지 차근차근 살펴봅니다.

이더리움 트랜잭션 영수증이란

트랜잭션을 공방에 맡긴 작업 주문서라고 생각해 보세요. 영수증은 기계가 멈춘 뒤 돌아오는 작업 결과표예요. 주문서는 무엇을 요청했는지 보여 주고, 결과표는 최상위 작업이 성공했는지, 얼마나 많은 작업량을 썼는지, 어떤 알림을 남겼는지 알려 줍니다.

트랜잭션 객체에는 발신자, 수신자, 논스(Nonce), 전송 가치, 가스 한도, 수수료 조건, 콜데이터(Calldata)가 들어갑니다. 반면 영수증은 실행되고 블록에 포함된 뒤 만들어져요. 의도가 아니라 결과를 기록합니다.

프로토콜 수준의 기존 영수증은 상태(Status), 누적 가스 사용량(Cumulative Gas Used), 로그 블룸(Logs Bloom), 로그(Logs)라는 네 가지 핵심 요소를 담습니다. JSON-RPC 응답은 여기에 트랜잭션 해시, 블록 정보, 발신·수신 주소, 개별 가스 사용량, 실효 가스 가격, 트랜잭션 타입, 생성된 컨트랙트 주소 같은 편리한 정보를 더해 보여 줘요.

트랜잭션 입력과 실행 결과의 차이

두 객체가 답하는 질문은 다릅니다.

이더리움 콜데이터는 어떤 함수와 인자가 제출됐는지 알려 줍니다. 영수증은 그 요청이 어떻게 끝났는지를 알려 줘요. 어느 하나만으로 모든 내부 호출, 상태 변화, 반환값을 알 수는 없습니다.

eth_getTransactionReceipt 읽는 법

표준 JSON-RPC 메서드는 트랜잭션 해시 하나를 받습니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionReceipt",
  "params": ["0xTransactionHash"]
}

결과는 영수증 객체 또는 null입니다. null이라고 해서 영구 실패가 확정된 것은 아니에요. 아직 대기 중이거나, 해당 노드가 거래를 모르거나, 해시 또는 네트워크가 틀렸을 수 있습니다. 결론을 내리기 전에 체인과 해시를 확인하고 신뢰할 수 있는 RPC 엔드포인트에서 다시 조회하세요.

신원과 블록 포함 필드

• transactionHash: 제출한 트랜잭션을 식별합니다.
• transactionIndex: 블록 안에서 트랜잭션의 위치를 표시해요.
• blockHash, blockNumber: 현재 거래를 포함한 블록을 식별합니다.
• from, to: 발신자와 목적지예요. 컨트랙트 생성 거래의 to는 null입니다.
• type: RPC가 보여 주는 트랜잭션 봉투 타입(Transaction Envelope Type)입니다.

블록 포함(Inclusion)과 최종성(Finality)은 다릅니다. 최신 블록은 재구성(Reorganization)될 수 있어요. 중요한 정산이라면 첫 영수증을 되돌릴 수 없는 결과로 취급하지 말고 확인 횟수나 최종성 정책을 적용해야 합니다. 자세한 경계는 블록체인 최종성 가이드에서 확인할 수 있어요.

상태와 컨트랙트 생성

비잔티움(Byzantium) 이후 트랜잭션의 status는 최상위 실행 성공 시 0x1, 실패 시 0x0입니다. EIP-658은 REVERT 명령 도입 뒤 ‘가스를 전부 썼는가’만으로 실패를 판정할 수 없게 되자 이 상태 코드를 도입했어요.

성공 상태는 최상위 EVM 실행이 되돌려지지 않았다는 뜻입니다. 모든 하위 호출이 성공했다는 뜻은 아니에요. 컨트랙트가 실패한 저수준 호출을 처리하거나 무시한 뒤 전체 실행은 성공으로 끝낼 수 있습니다. 목적지의 신원, 자산 가치, 스왑의 공정성도 보증하지 않아요.

컨트랙트 생성 거래라면 contractAddress에 생성된 주소가 표시됩니다. 일반 거래라면 null이에요. 다시 상호작용하기 전에 의도한 체인의 해당 주소에 실제 코드가 있는지 확인하세요.

가스 필드와 실제 실행 비용

gasUsed는 이 트랜잭션 하나가 사용한 가스예요. cumulativeGasUsed는 같은 블록에서 앞선 거래부터 현재 거래까지 사용한 누적 가스입니다. 내 거래 하나의 비용이 아닙니다.

일반 실행 가스 비용은 다음처럼 이해할 수 있어요.

지불한 실행 수수료 = gasUsed × effectiveGasPrice

effectiveGasPrice는 해당 수수료 규칙에 따라 실제로 부과된 가스당 가격입니다. 사용자가 정한 최대 수수료 상한과 항상 같지는 않아요. 가스 한도 가운데 쓰지 않은 분량을 전부 사용한 것처럼 청구하지도 않습니다.

블롭 트랜잭션(Blob Transaction)은 blobGasUsed와 blobGasPrice도 표시할 수 있어요. 이는 일반 EVM 실행 가스와 별도의 블롭 데이터 가스입니다. 블롭 거래의 전체 비용을 gasUsed × effectiveGasPrice만으로 계산하면 빠지는 항목이 생길 수 있습니다.

기본 수수료(Base Fee), 우선 수수료(Priority Fee), 상한과 환불 구조는 가스비 가이드에서 더 자세히 설명합니다.

로그와 블룸 필터가 보여 주는 것

logs 배열에는 실행 중 발생해 최종적으로 살아남은 이벤트가 들어갑니다. 각 로그는 이벤트를 낸 주소와 인덱싱된 topics, ABI로 인코딩된 data를 담아요. 최상위 트랜잭션이 되돌려지면 그 상태 변화와 로그는 영수증에 남지 않습니다.

logsBloom은 특정 주소나 토픽이 확실히 없는 블록·영수증을 빠르게 건너뛰기 위한 확률적 필터입니다. 일치하더라도 후보일 뿐이에요. 블룸 필터는 거짓 양성(False Positive)이 가능하므로 실제 로그를 확인해야 합니다.

이더리움 이벤트 로그 가이드에서는 이벤트 시그니처, 토픽 위치, 디코딩, 체인 재구성에 안전한 인덱싱 방법을 설명합니다.

타입 영수증과 영수증 루트

영수증은 블록 탐색기가 임의로 붙인 메모가 아닙니다. 이더리움은 영수증을 머클 패트리샤 영수증 트라이(Merkle-Patricia Receipts Trie)에 넣고, 블록 헤더에 receipts_root를 기록해요. 올바른 트라이 증명과 신뢰할 수 있는 블록 헤더가 있다면 특정 인코딩 영수증이 해당 블록에 속하는지 검증할 수 있습니다.

EIP-2718은 트랜잭션과 영수증에 타입 봉투(Typed Envelope)를 도입했습니다. 타입 영수증은 대응하는 트랜잭션 타입과 그 타입의 영수증 페이로드로 구성되고, 기존 영수증은 기존 인코딩을 유지해요. RPC 객체는 개발자가 읽기 편한 표현이지, 트라이에 들어가는 정확한 바이트열과 항상 같지는 않습니다.

영수증 증명을 만들 때 이 차이가 중요합니다. 임의 순서로 JSON 객체를 직렬화하면 안 돼요. 합의 인코딩, 블록 안의 트랜잭션 인덱스, 트라이 경로가 필요합니다. 이더리움 머클 패트리샤 트라이 가이드에서 루트와 포함 증명의 연결을 확인해 보세요.

영수증이 증명하지 못하는 것과 리스크

전체 실행 추적을 보여 주지 않아요

영수증에는 모든 내부 호출, 연산 코드, 저장소 쓰기, 되돌림 사유가 나열되지 않습니다. 디버그 트레이싱(Debug Tracing)이나 상태 차이 도구가 더 많은 정보를 줄 수 있지만, 제공 여부와 RPC 형식은 클라이언트·서비스마다 다를 수 있어요.

성공이 의도한 경제적 결과를 뜻하지 않아요

컨트랙트가 실패한 내부 호출을 처리하고 성공으로 끝낼 수 있습니다. 불리한 가격으로 스왑되거나, 가짜 토큰이 전송되거나, 사용자가 생각한 것과 다른 로직이 실행돼도 status는 성공일 수 있어요. 예상 잔액, 소유권, 승인 한도, 프로토콜 상태를 따로 확인해야 합니다.

영수증이 블록을 최종 확정하지 않아요

블록 해시는 현재 포함 위치를 나타냅니다. 서비스는 체인 재구성을 처리하고 결과의 중요도에 맞는 확인 정책을 정해야 해요.

탐색기 디코딩이 틀릴 수 있어요

사람이 읽는 라벨은 컨트랙트 메타데이터와 ABI에 의존합니다. 결과가 중요하다면 체인, 주소, 검증된 소스, 원시 필드를 직접 확인하세요.

실전 확인 체크리스트

• 체인 ID와 트랜잭션 해시가 맞는지 확인하기
• 영수증이 null이 아닌지 보고 블록 해시 기록하기
• 로그를 해석하기 전에 status 읽기
• gasUsed와 cumulativeGasUsed 구분하기
• 해당하면 블롭 가스까지 비용에 포함하기
• 이벤트 발행 주소와 생성된 컨트랙트 주소 검증하기
• 올바른 네트워크와 ABI로 로그 디코딩하기
• 예상 결과를 실제 잔액·컨트랙트 상태와 대조하기
• 확인 횟수 또는 최종성 정책 적용하기
• 영수증 증명에는 임의 JSON이 아닌 합의 인코딩 사용하기

FAQ

트랜잭션 영수증이 null인 이유는 무엇인가요?

아직 대기 중이거나, 조회한 노드가 거래를 모르거나, 다른 체인에 제출했거나, 노드의 풀에서 제거됐거나, 해시가 틀렸을 수 있습니다. 네트워크와 해시를 확인한 뒤 필요하면 다른 신뢰할 수 있는 RPC에서 조회하세요.

상태가 성공인데 토큰 전송은 실패할 수 있나요?

가능합니다. 최상위 컨트랙트가 실패한 내부 호출을 처리하고 되돌리지 않을 수 있어요. 또는 사용자가 예상한 것과 다른 로직이 실행됐을 수 있습니다. 상태뿐 아니라 로그와 실제 상태 변화를 확인해야 합니다.

cumulativeGasUsed가 내 수수료인가요?

아닙니다. 같은 블록의 앞선 트랜잭션이 쓴 가스까지 포함해요. 내 거래의 gasUsed와 effectiveGasPrice를 사용하고, 해당하면 블롭 가스 필드도 포함하세요.

영수증이 블록에 포함됐다는 것을 증명할 수 있나요?

가능합니다. 정확히 인코딩한 영수증, 트랜잭션 인덱스 기반 트라이 키, 영수증 트라이 증명, 일치하는 영수증 루트를 가진 신뢰할 수 있는 블록 헤더가 필요해요. 블록 탐색기의 JSON 화면만으로는 이 증명이 완성되지 않습니다.

주요 출처

• Ethereum Execution APIs: eth_getTransactionReceipt
• Ethereum.org: Transactions
• Ethereum.org: Blocks and the receipts root
• EIP-658: Embedding transaction status code in receipts
• EIP-2718: Typed Transaction Envelope
• Ethereum Execution Specifications: Receipt data structure and encoding

실행 결과를 읽고 실제 결과를 다시 확인하세요

이더리움 트랜잭션 영수증은 상태, 가스 회계, 로그, 블록 안의 위치를 담은 실행 결과표입니다. 원래 트랜잭션, 현재 상태, 최종성 요구사항과 함께 읽어야 해요. 이 글은 교육 목적이며 투자 조언이 아닙니다. 온체인 시스템과 자산은 실패하거나 가치를 잃을 수 있어요. 잃어도 되는 범위에서 조심스럽게 테스트하고, 반드시 스스로 조사하세요(DYOR).