gRPC
Sui 풀 노드 gRPC는 Sui blockchain과 상호작용하기 위한 빠르고, 타입 안전하며, 효율적인 인터페이스를 제공한다. 파워 유저, 인덱서, explorer, 탈중앙화 앱을 위해 설계된 이 API는 높은 성능과 낮은 지연 시간으로 Sui 데이터에 접근할 수 있게 한다.
JSON-RPC is deprecated. Migrate to either gRPC or GraphQL RPC by July 2026.
Refer to the list of RPC or data providers that have enabled gRPC on their full nodes or offer GraphQL RPC. Contact a provider directly to request access. If your RPC or data provider doesn’t yet support these data access methods, ask them to enable support or contact the Sui Foundation team on Discord, Telegram, or Slack for help.
gRPC는 빠르고 컴팩트한 데이터 직렬화를 위해 Protocol Buffers를 사용하는 고성능의 효율적인 통신 프로토콜을 제공한다. 강한 타입 인터페이스는 런타임 오류를 줄이고 여러 언어에서 클라이언트 및 서버 개발을 단순화한다.
gRPC API는 풀 노드에서 JSON-RPC를 대체한다. JSON-RPC는 deprecated되었고 gRPC API는 generally available이다. 둘 사이의 메시지 및 요청 형식 변경 외에도 gRPC API에는 몇 가지 핵심 기능 차이가 있다:
-
레코드를 폴링하지 않고도 애플리케이션에서 실시간 스트리밍 데이터를 소비하기 위해 스트리밍 또는 구독 API 엔드포인트를 사용한다. 이 지원은 JSON-RPC에서 deprecated된 WebSocket 지원을 대체한다.
-
과거 데이터에 대해 Sui Foundation-managed Archival Store for historical data가 없다. 풀 노드 운영자, RPC provider, data indexer operator는 과거 데이터를 가져오기 위한 명시적 의존성이 될 수 있는 유사한 Archival Store 인스턴스를 자체적으로 실행하는 것이 권장된다.
High-level release timeline
아래 표시된 목표 시점은 잠정적이며 프로젝트 진행 상황과 사용자 피드백에 따라 업데이트될 수 있다.
| Tentative time | Milestone | Description |
|---|---|---|
| ✔️ April 2025 | 초기 polling-based APIs 세트의 beta 릴리스 | 애플리케이션에서 초기 gRPC 통합을 검증하기 시작하고 보고 싶은 개선 사항에 대한 피드백을 공유할 수 있다. |
| ✔️ July 2025 | 스트리밍 APIs 및 남은 polling-based APIs 세트의 beta 릴리스 | 사용 사례에 스트리밍 저지연 데이터가 필요하다면 이 시점이 해당 통합 검증을 시작하기에 적절하다. 또한 이 시점에 API 범위의 기능이 완전해지므로 프로덕션이 아닌 환경에서 애플리케이션 마이그레이션을 시작할 수 있다. |
| ✔️ September-October 2025 | polling-based 및 streaming APIs의 GA 릴리스 | 프로덕션 환경에서 애플리케이션의 마이그레이션과 컷오버를 시작한다. 이 시점에 JSON-RPC는 deprecated되며 마이그레이 션 고지 기간이 시작된다. |
| July 2026 | 마이그레이션 타임라인 종료 | 이 시점에 JSON-RPC는 완전히 비활성화된다. |
gRPC 및 GraphQL RPC APIs가 JSON-RPC를 대체했다. 마이그레이션 타임라인과 어떤 API를 사용해야 하는지 알아보려면 아래 비디오를 확인하라.
When to use
내장된 코드 생성 지원을 통해 TypeScript, Go, Rust 등의 클라이언트를 스캐폴드할 수 있다. 이로 인해 인덱서, blockchain explorer, 데이터 집약적인 탈중앙화 앱과 같은 확장 가능한 백엔드 시스템에 적합하다.
요청-응답 호출 외에도 gRPC는 서버 측 스트리밍을 지원하여 지속적인 폴링 없이 실시간 데이터 전달을 가능하게 한다. 이는 events와 transactions를 실시간으로 추적해야 하는 환경에 서 특히 유용하다. gRPC의 바이너리 형식은 JSON보다 훨씬 빠르고 가벼워 대역폭을 절약하고 지연 시간을 개선한다.
How gRPC fits into the application stack
Sui에서는 다음 gRPC 서비스를 사용할 수 있다. Protocol buffers가 gRPC 인터페이스를 정의한다. sui-apis on GitHub에서 관련 .proto 파일을 찾을 수 있으며, 여기에는 gRPC 메시지(요청 및 응답 페이로드) 외에도 다음 서비스가 포함된다:
| Service | .proto file | Purpose |
|---|---|---|
TransactionExecutionService | sui/rpc/v2/transaction_execution_service.proto | Sui 네트워크에서 서명된 transactions를 제출하고 실행한다. 지갑과 앱은 이 서비스를 사용하여 사용자 액션을 네트워크로 전송한다. |
LedgerService | sui/rpc/v2/ledger_service.proto | Sui 네트워크의 현재 상태와 최근 이력에서 특정 checkpoints, transactions, objects 등을 조회한다. 이력은 full node가 유지하는 범위로 제한된 최근 과거를 가리킨다. |
StateService | sui/rpc/v2/state_service.proto | balances, coin metadata, dynamic fields, owned objects와 같은 최신 온체인 데이터를 조회한다. 또한 transactions에 대한 dry-run simulations도 지원한다. |
SubscriptionService | sui/rpc/v2/subscription_service.proto | checkpoints에 대한 실시간 업데이트를 스트리밍한다. 인덱서, bots, dashboards와 같은 반응형 시스템을 구축하는 데 적합하다. 스트리밍 데이터는 Subscriptions를 참조하라. |
MovePackageService | sui/rpc/v2/move_package_service.proto | Sui 네트워크에 배포된 Move packages의 metadata와 콘텐츠에 접근한다. tooling, 분석, 스마트 계약 인트로스펙션에 유용하다. |
SignatureVerificationService | sui/rpc/v2/signature_verification_service.proto | transaction 실행 외부에서 signatures를 검증한다. zkLogin 통합 또는 다른 signatures를 포함할 수 있는 payload를 사전 검증하거나, 인증을 시뮬레이션하거나, 커스텀 signing workflows를 구축하는 데 도움이 된다. |
NameService | sui/rpc/v2/name_service.proto | 사람이 읽을 수 있는 SuiNS 이름을 기반 name records로 해석하고, Sui addresses에서 연결된 이름으로 역방향 조회를 수행한다. |
이 정의를 사용하여 다양한 프로그래밍 언어의 클라이언트 라이브러리를 생성한다.
이전에 v2beta2 .proto 파일을 사용했다면 최신 정의는 이제 v2 버전 아래에 있다. 또한 LiveDataService는 StateService로 이름이 바뀌었고 SimulateTransaction API는 TransactionExecutionService로 이동했다.
Subscriptions for streaming data
SubscriptionService는 gRPC 서버 측 스트리밍 APIs를 통해 온체인 활동에 대한 실시간 스트리밍 업데이트를 제공한다. 예를 들어 SubscribeCheckpoint RPC를 사용하면 실행된 checkpoints의 전역 스트림을 구독할 수 있다. 구독이 초기화되면 스트림은 서버가 알고 있는 최신 checkpoint에서 시작된다. Checkpoints는 순서대로 누락 없이 도착하는 것이 보장된다. 이를 통해 클라이언트는 마지막으로 처리한 checkpoint를 정확히 추적할 수 있다.
클라이언트 연결 해제 또는 네트워크 오류로 스트림이 중단되면 다른 APIs를 사용해 누락된 데이터를 백필한 뒤 다시 구독하여 마지막으로 알려진 checkpoint부터 재개할 수 있다.
스트리밍 APIs는 최소 지연 시간으로 실시간 Sui 활동에 반응해야 하는 인덱서, dashboards, bots를 구축하는 데 유용하다.
Handling pruned data
full node가 특정 object, transaction, 또는 event를 반환하지 않는다면 해당 데이터는 node의 리텐션 구성에 따라 pruning되었을 가능성이 높다. 그런 경우 애플리케이션에서 아카이브 서비스 사용하기로부터 동일한 데이터를 조회하는 폴백 메커니즘을 사용하라. Archival Store는 네트워크의 과거 데이터를 보존한다.
이 조회에는 동일한 gRPC LedgerService methods를 재사용할 수 있다. 클라이언트의 엔드포인트를 full node address에서 Archival Service 엔드포인트로 간단히 변경하라. 이렇게 하면 full node의 pruning 설정과 관계없이 애플리케이션이 최신 데이터와 과거 데이터 모두에 안정적으로 접근할 수 있다.
Best practices
-
특히 큰 리소스의 경우 응답 크기와 지연 시간을 줄이기 위해 적용 가능한 곳에서는 항상 필드 마스크를 사용한다.
-
암호화된 전송을 보장하고 다운그레이드 공격을 방지하기 위해 프로덕션 트래픽에는
TLS (port 443)를 사용한다. -
반복적으로 폴링하는 대신 실시간 사용 사례에는 스트리밍 subscriptions를 사용한다.
-
호환성과 타입 안전성을 보장하기 위해
sui-apis의 공식.proto정의에서 클라이언트 코드를 생성한다. -
Paginate를 신중하게 수행한다. 항상
next_page_token을 확인하고 모든 데이터가 한 번에 반환된다고 가정하지 않는다. -
특히 스트리밍 APIs나 혼잡한 public nodes에 대해서는 exponential backoff를 사용해 일시적 실패를 재시도한다.
-
디버깅이 어려운 API 거부를 방지하기 위해 encodings와 메시지 형식을 포함한 모든 입력 데이터를 검증한다.
Frequently asked questions
Can I use field masks in batch requests?
BatchGetObjects와 같은 batch 요청에서는 최상위 read_mask 필드만 적용된다. 개별 GetObjectRequest 항목 내의 field masks는 무시된다.
Why does the API return fewer results than the requested page_size?
특정 page_size를 요청하더라도 서버는 더 적은 수의 항목을 반환할 수 있다. 이는 full node별 제한, 필터링된 결과, 또는 사용 가능한 데이터의 끝에 도달한 것 때문일 수 있다.
Why do some fields say optional if they're required?
proto3에서 필드를 optional로 표시하면 API가 field presence, 즉 필드 값이 명시적으로 설정되었는지 아니면 단순히 기본값으로 처리되었는지를 감지할 수 있게 된다. 이것이 실제로 해당 필드가 선택 사항이라는 뜻은 아니다. 요청이 유효하도록 하려면 여전히 API 계약을 따라야 한다.
Are all services and related data guaranteed to be available on all full nodes?
full nodes는 지원하는 services와 리텐션이 다를 수 있다. 일부 services는 아직 지원되지 않을 수 있으며 일부 APIs는 node 구성 및 데이터 가용성에 따라 NOT_FOUND를 반환할 수 있다.