🔧 HIP‑1217: Hedera /api/v1/contracts/call 엔드포인트 주요 업데이트

HIP‑1217은 Hedera 미러 노드 API 엔드포인트 /api/v1/contracts/call에 대한 주요 개선사항을 설명합니다. 이번 업데이트는 모듈화된 실행 흐름을 도입하여 Consensus 노드와 동일한 방식으로 작동하도록 조정되어, 더 정확하고 신뢰할 수 있는 스마트 계약 실행 환경을 제공합니다.

❓ 왜 바뀌는 걸까요?

기존에는 Hedera EVM (이더리움 가상 머신)이 단일(monolithic) 구조로 운영돼 왔습니다. 이 경우, 미러 노드에서 시뮬레이션한 호출과 실제 Consensus 노드 동작 간에 차이가 발생할 수 있었습니다. HIP‑1217 적용 시 다음과 같은 개선이 이루어집니다:

⛽ 가스 예측 정확도 향상
🔄 Consensus 노드와 미러 노드 간 일관된 동작 보장
🐞 디버깅 간소화 및 상세 오류 코드 제공

🛠 주요 변경사항 및 개발자가 알아야 할 점

1. 주소 해석 (Address Resolution)

변경 영향:

ED25519 계정은 Number Alias(0x0000…) 사용
ECDSA 계정은 Keccak‑256 alias(0xc5b7…) 사용
Keccak alias가 없는 ECDSA 계정은 Number Alias 사용 가능

조치:

Mirror 노드 API의 evm_address 또는 SDK의 contractAccountId 활용
ECDSA 계정은 Keccak‑256 alias 형식을 사용

배포일: 2025년 12월 1일

2. 지불자 잔액 확인 (Payer Balance Validation)

변경 영향: 잔액 부족 시 INSUFFICIENT_PAYER_BALANCE 오류 발생 가능
조치: 시뮬레이션 호출(eth_call) 전에도 충분한 잔액 확보
배포일: 2025년 12월 1일

3. 입력 오류 처리 (Invalid Input Handling)

변경 영향: INVALID_CONTRACT_ID 등 더 구체적인 오류 상태 반환
조치: 클라이언트 로직에서 보다 다양한 오류 코드와 HTTP 400 처리
배포일: 2025년 9월 1일

4. 가스 추정 (Gas Estimation)

변경 영향: 특히 컨트랙트 배포 시 가스 예측 수치가 보다 정확하게 변경
조치: 테스트 및 애플리케이션의 가스 예상값 조정
배포일: 2025년 9월 1일

5. 기본 KYC 상태 (Default KYC Status)

변경 영향: 실제 Consensus 상태에 기반한 KYC 반환값 반영
조치: 기본 KYC 상태에 의존하는 로직 검토 및 수정
배포일: 2025년 9월 1일

6. 반환값과 예외 처리 (Return Values vs Exceptions)

변경 영향: 기존에 기본값 반환하던 호출은 에러로, 또는 그 반대의 경우 발생 가능
조치: 예외 기반 및 값 기반 응답 모두 처리 가능한 클라이언트 로직 작성
배포일: 2025년 9월 1일

7. 존재하지 않는 컨트랙트 호출 (Call to Nonexistent Contracts)

변경 영향: 이전 INVALID_TRANSACTION → 이제는 INVALID_CONTRACT_ID 반환
조치: 오류 처리 로직 업데이트
배포일: 2025년 9월 1일

8. 리디렉션 오류 처리 통일 (Redirect Call Errors)

변경 영향: 특정 오류 코드(예: INVALID_TOKEN_ID) 대신 CONTRACT_REVERT_EXECUTED 공통 반환
조치: 테스트 및 오류 처리 로직 수정
배포일: 2025년 9월 1일

⚠️ 호환성 안내

이번 변경은 이전 버전과 호환되지 않으며, 개발자는 애플리케이션을 반드시 업데이트해야 합니다. 그렇지 않으면 오류나 예기치 않은 실패가 발생할 수 있습니다.

⏳ 임시 우회 및 마이그레이션 지원

Address Resolution 및 Payer Balance Validation 관련 변경은 2025년 12월 1일까지 유예됩니다.
더 긴 유예 기간이 필요하다면 Discord에서 reccetech (Keith Kowal) 에 요청하실 수 있으며, 맞춤형 마이그레이션 일정을 지원합니다.

🧩 미러 노드 운영자용 안내

미러 노드 운영자는 다음 환경 변수를 설정하여 인스턴스에 모듈화 흐름을 활성화할 수 있습니다:

테스트 및 배포 계획에 따라 HEDERA_MIRROR_WEB3_EVM_MODULARIZEDTRAFFICPERCENT 값을 조정하십시오.

📅 다음 단계 & 일정 요약

저희는 개발자들이 Previewnet 및 Testnet에서 애플리케이션을 테스트할 것을 강력히 권장합니다. 현재 Previewnet 및 Testnet에서는 모듈화된 흐름이 활성화되어 있으며 전체 트래픽의 100%를 처리하고 있습니다. 이는 메인넷 출시 전 원활한 전환을 보장하고 필요한 조정 사항을 사전에 식별하는 데 도움이 될 것입니다.