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

Set up RPC node for Midnight

RPC(Remote Procedure Call) 노드는 애플리케이션이 Midnight blockchain과 프로그래밍 방식으로 상호작용하는 주요 인터페이스 역할을 합니다. 이 노드는 WebSocket과 HTTP API를 노출해, 개발자가 트랜잭션을 제출하고, blockchain 데이터를 조회하며, 이벤트를 구독하고, DApp을 네트워크와 통합할 수 있습니다.

이 가이드는 Midnight blockchain에서 RPC node를 설정하는 단계별 방법을 안내합니다.

Prerequisites​

Midnight RPC node 설정 전에 다음 사항을 준비하세요:

Run the Midnight node in RPC mode​

다음 명령어로 Midnight node를 RPC 모드로 실행합니다. 대상 네트워크에 맞는 설정을 선택하세요.

노드는 홈 디렉터리에서 시작하세요. 시작 시 노드는 명령을 실행한 디렉터리를 기준으로 res/cfg에서 설정을 읽습니다. CFG_PRESET 환경 변수로 네트워크를 선택합니다. CARDANO_SECURITY_PARAMETER는 대응하는 Cardano 네트워크의 security parameter로, Preview는 432, Preprod는 2160입니다. Preview chain specification에는 boot node가 하나도 없어서, Preview 명령은 known Preview boot nodes를 --bootnodes로 전달합니다.

기본적으로 노드는 RPC 인터페이스를 localhost(127.0.0.1와 [::1])에 바인딩합니다. 명령은 --rpc-methods Safe도 함께 전달하므로 노드는 Safe 메서드 세트만 제공합니다. 이 설정을 시작점으로 권장합니다. endpoint가 로컬 머신에서만 접근 가능하므로 인터넷에 직접 노출되지 않습니다. 외부 클라이언트가 사용하게 하려면, 노드 자체를 public 인터페이스에 바인딩하지 말고 그 앞에 보안을 강화한 reverse proxy를 두세요. Exposing the RPC endpoint를 참고하세요.

CFG_PRESET=preview CARDANO_SECURITY_PARAMETER=432 midnight-node \
  --chain /home/midnight/res/preview/chain-spec-raw.json \
  --base-path /home/midnight/data \
  --rpc-port 9944 \
  --rpc-methods Safe \
  --bootnodes /dns/bootnode-1.preview.midnight.network/tcp/30333/ws/p2p/12D3KooWK66i7dtGVNSwDh9tTeqov1q6LSdWsRLJvTyzTCaywYgK \
  --bootnodes /dns/bootnode-2.preview.midnight.network/tcp/30333/ws/p2p/12D3KooWHqFfXFwb7WW4jwR8pr4BEf562v5M6c8K3CXAJq4Wx6ym

Configure RPC methods​

  • --rpc-port 9944: RPC 서버가 수신할 TCP 포트입니다.
  • --rpc-methods Safe: 안전한 RPC 메서드 세트만 노출합니다. 이 플래그가 없으면 노드는 Auto를 사용하는데, Auto는 RPC가 localhost에서 수신할 때 reverse proxy를 거치더라도 모든 메서드를 노출합니다. localhost 밖에서 접근 가능한 노드에서는 Unsafe/Auto를 사용하지 마세요. 노드를 제어할 수 있는 메서드까지 노출하기 때문입니다.

Exposing the RPC endpoint​

Public RPC 노드의 경우, 노드는 localhost에 바인딩한 상태(위 기본값)로 두고, TLS를 처리하고 허용 origin을 제한하며 rate limiting을 적용하는 reverse proxy(예: nginx, Caddy)를 앞단에 두는 방식을 권장합니다. 여기에 P2P 포트와 proxy 포트만 허용하는 방화벽을 함께 사용하세요.

노드는 Host 헤더가 localhost:9944, 127.0.0.1:9944, [::1]:9944인 요청만 받습니다. 9944 자리에는 여러분의 RPC 포트가 들어갑니다. proxy가 Host 헤더로 localhost:9944를 보내도록 설정하세요. 그 밖의 Host 값은 Provided Host header is not whitelisted 메시지와 함께 403 응답을 받습니다. 노드를 --rpc-external로 실행할 때 노드의 public 주소로 보낸 요청도 여기에 해당합니다. 노드를 --rpc-cors all로 실행하면 이 검사가 꺼지지만, 그러면 모든 origin의 요청도 허용됩니다.

노드는 아래 플래그로 RPC를 직접 노출할 수도 있습니다. 이 플래그들은 localhost 기본값을 우회하므로, 신뢰할 수 있고 방화벽이 적용된 네트워크에서만 사용하고, 앞단에 proxy 없이 공개 인터넷에 노출해서는 안 됩니다.

warning

RPC 인터페이스를 public 주소에 바인딩하면서 CORS를 느슨하게 두면, 노드가 악용, 리소스 고갈, 데이터 스크래핑에 노출됩니다. 아래 옵션은 고급 설정으로 다루고, 방화벽, TLS, 범위를 제한한 origin으로 보호하세요.

  • --rpc-external: RPC 서버를 모든 인터페이스에 바인딩해 외부 네트워크에서 접근할 수 있게 합니다. 이 플래그가 없으면 RPC는 localhost(127.0.0.1와 [::1])에 머뭅니다. 통합 RPC 서버가 이 인터페이스에서 HTTP와 WebSocket 연결을 모두 처리합니다.
  • --rpc-cors <origins>: 허용할 CORS origin을 설정합니다. 모든 origin의 요청을 허용하는 all보다, 신뢰할 수 있는 도메인을 쉼표로 구분한 명시적 목록(예: --rpc-cors https://app.example.com)을 권장합니다.

--no-private-ip 플래그는 RPC endpoint에는 영향을 주지 않습니다. 이 플래그는 노드가 네트워크에서 발견한 private IPv4·IPv6 주소에 연결하지 못하게 합니다. Preview, Preprod, Mainnet은 chain specification이 live로 표시되어 있어 기본적으로 켜져 있습니다.

Test connectivity​

노드의 P2P 포트(기본값: 30333)가 열려 있고 네트워크 통신이 가능한지 확인하세요. telnet, netcat, nmap 같은 도구로 포트 상태를 점검하고, 노드가 네트워크에 올바르게 연결되어 있는지 검증합니다.

사용 가능한 RPC 메서드를 확인하려면 다음 curl 명령어를 실행하세요. 노드가 노출하는 모든 endpoint 목록이 출력됩니다:

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{
           "jsonrpc":"2.0",
           "id":1,
           "method":"rpc_methods",
           "params":[]
         }' \
     http://127.0.0.1:9944

Next steps​

RPC node를 설정했다면, Node endpoints를 사용해 Midnight blockchain과 상호작용할 수 있습니다.