Skip to main content
Version: v1
For the complete documentation index, see llms.txt

RPC interface

RPC 레이어를 통해 외부 클라이언트(DApp, 지갑, 익스플로러, 서비스 등)가 HTTP/HTTPS 또는 WebSocket 연결로 실행 중인 Midnight 노드와 상호작용할 수 있습니다. Midnight의 RPC는 JSON-RPC 표준을 따르며 다음 용도의 메서드를 노출합니다:

  • 트랜잭션 제출(상태 전환 트리거)
  • 컨트랙트 상태 조회(온체인)
  • 보조 데이터 조회(오프체인 또는 메타데이터)

이러한 메서드가 Midnight 기반 도구와 애플리케이션 구축을 위한 인터페이스를 구성합니다.

Core RPC methods​

Midnight 노드는 midnight_ 네임스페이스에 다음과 같은 커스텀 RPC 메서드를 노출합니다. 이들은 컨트랙트 상태, ledger state 루트, 버전 정보를 반환합니다. 선택적 at 파라미터는 블록 해시입니다. 생략하면 쿼리는 노드의 best block을 대상으로 실행되는데, 이 블록은 아직 최종 확정되지 않았을 수 있습니다.

#[method(name = "midnight_contractState")]
fn get_state(
    &self,
    contract_address: String,
    at: Option<BlockHash>,
) -> Result<String, StateRpcError>;

배포된 스마트 컨트랙트의 상태를 hex 인코딩 문자열로 반환합니다. 컨트랙트 주소는 0x 접두사 없는 hex 문자열로 전달하세요.

#[method(name = "midnight_zswapStateRoot")]
fn get_zswap_state_root(&self, at: Option<BlockHash>) -> Result<Vec<u8>, StateRpcError>;

Zswap coin commitment 트리의 Merkle 루트를 바이트 배열로 반환합니다.

#[method(name = "midnight_ledgerStateRoot")]
fn get_ledger_state_root(&self, at: Option<BlockHash>) -> Result<Vec<u8>, StateRpcError>;

ledger state의 루트를 바이트 배열로 반환합니다. 이 배열은 0 바이트 뒤에 32바이트 Merkle 루트 해시가 오거나, 1 바이트 뒤에 루트 노드 자체가 옵니다. 두 번째 형태는 루트 노드가 인라인으로 저장될 만큼 작을 때 나타나므로, 길이가 블록마다 달라질 수 있습니다.

#[method(name = "midnight_apiVersions")]
fn get_supported_api_versions(&self) -> RpcResult<Vec<u32>>;

지원되는 모든 RPC API 버전을 나열합니다. 도구 호환성 확인에 유용합니다.

#[method(name = "midnight_ledgerVersion")]
fn get_ledger_version(&self, at: Option<BlockHash>) -> Result<String, BlockRpcError>;

노드가 지정한 블록에 사용하는 ledger 버전을 =8.1.2 같은 문자열로 반환합니다. 이 값은 노드의 빌드에서 나오므로, 오래된 블록의 경우 당시 네트워크가 실제로 실행하던 버전보다 더 최신일 수 있습니다.

Polkadot SDK RPC support​

Midnight은 다음 기본 Polkadot SDK RPC 메서드도 지원합니다:

  • system_health
  • chain_getBlock
  • state_getStorage
  • rpc_methods — 지원되는 모든 RPC 엔드포인트 목록을 반환합니다.

rpc_methods를 호출하면 노드가 노출하는 전체 메서드 목록을 언제든 동적으로 조회할 수 있습니다.

note

Midnight이 노출하는 RPC 메서드 중 일부는 Polkadot JS 웹 앱에 나타나지 않을 수 있습니다. 일반적인 참고 자료로는 Polkadot SDK RPC 메서드 문서를 확인하세요. Midnight 구현은 이 목록과 상당 부분 겹치지만, 노드 버전과 설정에 따라 지원 범위가 달라질 수 있습니다.

Partnerchain RPC​

Midnight은 블록 생산자 및 사이드체인 통합과 관련된 partnerchain 전용 RPC 메서드도 노출합니다. 이러한 메서드는 합의 신호 조회, 최종성 정보 중계, 체인 간 조율 등을 위해 설계되었습니다.

Security note for block producers​

warning

모든 RPC 메서드가 공개 또는 프로덕션 노드에서 노출하기에 안전한 것은 아닙니다.

블록 생성 노드를 운영 중이라면 어떤 RPC 엔드포인트가 활성화되어 있는지 주의해야 합니다. 일부 메서드는 민감한 데이터를 유출하거나 성능 위험을 초래할 수 있습니다.

위험을 최소화하려면:

  • --rpc-methods Safe 플래그로 노출 메서드를 안전한 하위 집합으로 제한하세요.
  • 반드시 필요한 경우가 아니라면 --rpc-external을 사용하지 마세요. RPC 인터페이스가 외부 네트워크에 노출됩니다.

노드의 RPC 구성이 의도한 위협 모델과 운영 역할(검증자 vs. 관찰자 등)에 부합하는지 항상 검토하세요.