TON 라이트서버 not ready: 원인과 ADNL 타임아웃 해결법

라이트서버 not ready: 단순한 요청을 보냈는데 "not ready"가 돌아옵니다

지갑 잔액을 확인하거나 컨트랙트의 get 메서드를 호출해야 하는 에이전트를 만들고 있다고 해봅시다. 코드도 맞고, 주소도 맞고, 라이트서버 설정은 공식 global-config.json에서 그대로 가져왔습니다. 그런데 응답 대신 not ready가 오거나, 아예 아무 응답도 없이 연결만 멈춰 있다가 ADNL 타임아웃으로 끊어집니다. 게다가 재현도 일정하지 않습니다. 아침에는 잘 되다가 부하가 걸리면 안 됩니다. 익숙한 이야기인가요? 이건 여러분 코드의 버그도 아니고 "TON이 죽었다"도 아닙니다. 글로벌 config에 들어 있는 공개 라이트서버의 지극히 예측 가능한 동작입니다. TON liteserver not ready가 왜 생기는지, 클라이언트 쪽에서 실제로 효과가 있는 건 무엇이고 없는 건 무엇인지 정리해보겠습니다.

TON 라이트서버의 "not ready"와 ADNL 타임아웃은 무슨 뜻인가

not ready는 라이트서버가 직접 하는 대답입니다. "나는 아직 동기화가 안 끝나서 답을 줄 수 없다"라는 뜻이죠. TON에는 블록체인 계층이 둘 있습니다. 마스터체인(masterchain), 그리고 샤드체인(shardchains) 즉 샤드로 나뉘는 basechain(워크체인 0)입니다. 마스터체인은 책의 목차 같은 것이고, 샤드는 트랜잭션과 계정 상태가 담긴 본문의 각 장입니다. 노드는 대응하는 shard 블록을 따라잡기 전에 마스터체인의 헤드를 먼저 받는 경우가 많습니다. 이 순간 마스터체인이 basechain보다 앞서 있고, 계정 상태는 최신 shard 블록에 들어 있어서 아직 확인할 수 없습니다. 그래서 노드는 낡거나 불완전한 데이터를 건네주는 대신 정직하게 not ready라고 답합니다.

ADNL 타임아웃은 같은 병에서 나오는 또 다른 증상입니다. ADNL은 TON의 네이티브 전송 프로토콜로, 라이트서버가 클라이언트와 대화하는 통로입니다(여기에 HTTP는 전혀 개입하지 않습니다). 노드에 부하가 걸리면 정해진 시간 안에 ADNL 요청에 응답하지 못하고, 클라이언트는 여러분의 비즈니스 로직에 닿아보지도 못하고 타임아웃으로 끊어집니다.

여기서 계층을 혼동하지 않는 게 중요합니다. not ready와 ADNL 타임아웃은 라이트서버의 네이티브 ADNL 프로토콜 계층에서 벌어지는 일입니다. 이건 toncenter나 tonapi.io 같은 HTTP 게이트웨이가 한도 초과 시 돌려주는 HTTP 429 Too Many Requests와 다릅니다. 계층이 다르고, 코드가 다르고, 원인이 다릅니다. 여러분이 실제로 싸우는 상대가 429라면 그건 별개의 이야기입니다. toncenter 429 해결법 분석을 보십시오. 그리고 TON 채팅방에 도는 "228 오류" 밈은 커뮤니티의 농담일 뿐 실제 코드가 아닙니다. 라이트서버는 그런 응답을 하지 않습니다.

글로벌 config의 공개 라이트서버가 부하에서 무너지는 이유

문제의 뿌리는 시시할 만큼 단순합니다. ton.org/global-config.json에 들어 있는 라이트서버는 공용이고 한도가 걸려 있습니다. 전 세계 개발자 수천 명과 봇, 인덱서, 에이전트가 동시에 두드리는 공개 자원입니다. 이런 자원에는 구조적인 제약이 셋 있습니다.

• 공용 부하. 여러분은 생태계 전체와 풀을 나눠 씁니다. 피크 때 노드는 네트워크의 헤드를 따라잡지 못하거나(여기서 not ready가 나옵니다), 아니면 제때 응답하지 못합니다(ADNL 타임아웃).
• 깊은 히스토리가 없습니다. 공개 노드는 깊은 아카이브를 보관하지 않습니다. lt/hash 쌍으로 오래된 트랜잭션을 찾아야 한다면 그 노드에는 이미 남아 있지 않을 수 있습니다. 히스토리를 다루는 이야기는 lt와 hash 정리에 따로 있습니다.
• 아무 보장도 없습니다. "있는 그대로" 제공되는 자원입니다. 우선순위도 없고, 처리량을 약속해주는 사람도 없습니다. 오늘은 운이 좋아도 내일은 아닐 수 있습니다.

즉 not ready는 "좀 기다리면 지나가는" 우연이 아니라, 부하 걸린 공용 자원의 필연적인 동작입니다. 그리고 여러분의 어떤 코드도 남의 과부하 노드를 더 빨리 동기화시키지는 못합니다.

클라이언트 쪽 처방: 재시도, 엔드포인트 로테이션, 타임아웃

인프라를 갈아엎기 전에 클라이언트에서 짜낼 수 있는 건 다 짜내십시오. 아래 기법들은 정직하게 효과가 있지만 천장이 있습니다. 노드가 여전히 공용이라는 사실은 그대로니까요.

1. 지수 백오프 재시도

not ready는 일시적인 경우가 많습니다. 200~800ms 뒤면 같은 라이트서버가 필요한 shard 블록을 이미 적용했을 수 있습니다. 지연을 늘려가며 단순히 다시 시도하는 것만으로도 오류의 상당 부분이 사라집니다.

async function withRetry<T>(fn: () => Promise<T>, tries = 4): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < tries; i++) {
    try {
      return await fn();
    } catch (e) {
      lastErr = e;
      // 'not ready'와 ADNL 타임아웃은 재시도하되, 비즈니스 오류는 제외
      await new Promise((r) => setTimeout(r, 200 * 2 ** i));
    }
  }
  throw lastErr;
}

2. 엔드포인트 로테이션

config에 있는 라이트서버 여러 개를 풀로 들고 있다가, 현재 노드가 not ready를 주거나 타임아웃으로 빠지면 다음 노드로 넘어가십시오. 한 노드가 뒤처져 있어도 옆 노드는 이미 따라잡았을 수 있습니다.

3. 타임아웃 상향

기본 ADNL 타임아웃은 과부하 상태의 공개 노드에는 지나치게 빡빡할 때가 있습니다. 몇 초 정도 여유를 두면 불필요한 연결 끊김이 줄어듭니다. 하지만 타임아웃을 무한정 늘리면 매달린 요청만 쌓일 뿐입니다. 치료가 아니라 마취입니다.

따로 챙길 만한 기법이 하나 더 있습니다. 실제 요청 전에 가벼운 healthcheck를 넣는 것입니다. get_masterchain_info(마스터체인 헤드)가 여기에 딱 맞습니다. 노드가 네트워크 헤드를 따라잡았을 때 최신 seqno를 가장 먼저 돌려주는 게 바로 이 작업이고, not ready를 내놓는 건 노드가 마스터체인 헤드 자체를 아직 못 따라잡았을 때뿐입니다. 최신 seqno가 돌아왔다면 노드는 정상이니 get_account_state, get_balance, run_get_method를 진행하면 됩니다.

정직한 결론: 재시도 + 로테이션 + 타임아웃은 오류 빈도를 낮춰주지만 원인을 없애지는 못합니다. 공개 노드는 설계상 과부하 상태이고, 여러분은 그저 똑같은 대기줄이 기다리는 문을 조금 더 조심스럽게 두드릴 뿐입니다. TON에 접근하는 다른 방법들은 2026년 toncenter 대안 정리에 모아두었습니다.

직접 노드를 돌리지 않는 해법: 우리 라이트서버 위의 TONNode hosted 키

not ready를 근본적으로 없애는 방법은 하나뿐입니다. 공용 노드에 가는 걸 그만두는 것입니다. 자체 TON 노드를 세우고 유지하는 건 비싸고 번거롭습니다. 동기화, 디스크, 업데이트, 모니터링이 줄줄이 따라옵니다. 그 중간 선택지는 공용 풀에 가는 대신, 키를 통해 보장된 처리량과 우선 접근을 받는 것입니다.

TONNode는 TON용 hosted MCP 서버입니다. MCP(Model Context Protocol)는 AI 에이전트(Claude, Cursor, ChatGPT/Codex, 그 밖의 모든 MCP 클라이언트)가 도구를 호출하는 방식을 정한 표준입니다. 여러분의 코드가 글로벌 config를 파싱하고 not ready를 피해 가며 곡예를 부리는 대신, 에이전트는 완성된 도구를 호출하고 그 뒤에서는 여러분의 Bearer 키를 단 hosted 엔드포인트 https://mcp.tonnode.io/mcp가 일합니다. 공용 대기줄이 아니라 보장된 처리량입니다.

@tonnode/mcp 패키지는 오픈소스(MIT, npm과 GitHub tonnode/mcp에 있습니다)이며 TON의 네이티브 ADNL 프로토콜로, HTTP 중간 계층 없이 동작합니다. 즉 느린 HTTP 게이트웨이로 전송 계층을 갈아타는 게 아니라 똑같이 정직한 ADNL 위에 남되, 여러분의 키에 우선 접근이 붙는 것입니다.

진단과 일상적인 읽기 작업에는 다음 도구들이 요긴합니다:

• get_masterchain_info — 마스터체인 헤드, 자연스러운 healthcheck입니다.
• get_account_state — 계정의 상태, 플래그, 마지막 트랜잭션.
• get_balance — GRAM 단위 잔액.
• run_get_method — 컨트랙트의 모든 읽기 전용 get 메서드.

TON에서 MCP를 이제 막 시작한다면 TON용 MCP 가이드부터 훑어보십시오.

연결 방법: 로컬 npx 또는 키를 단 hosted 엔드포인트

무료 로컬 실행

읽기 도구 전체가 공개 config 그대로, 카드도 키도 없이 로컬에서 바로 동작합니다:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

개발과 로컬 실험에는 훌륭합니다. 다만 기억하십시오. 로컬 npx는 내부적으로 여전히 같은 공용 라이트서버로 나갑니다. 그래서 부하 상황의 not ready를 막아주지는 못합니다. 대신 의존성 씨름에서 해방시켜주고 도구를 하나의 인터페이스로 묶어줍니다.

키를 단 hosted

공용 노드에서 벗어나려면 전송 계층을 자신의 Bearer 키를 단 HTTP-MCP로 바꾸십시오(도구 호출 자체는 ADNL로 우리 노드에 전달됩니다):

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

에이전트와 함께 쓰면 이런 모습입니다

연결이 끝나면 에이전트에게는 평범한 프롬프트 하나면 충분합니다. 도구는 알아서 고릅니다:

먼저 healthcheck로 get_masterchain_info를 호출해. 그다음 EQC…에 대해 get_account_state로 상태와 마지막 트랜잭션을 보여줘. 이어서 같은 주소로 get_balance.

내부적으로는 이런 체인입니다. get_masterchain_info(노드가 살아 있고 헤드를 따라잡았는지) → get_account_state(상태, 플래그, 마지막 트랜잭션) → get_balance(GRAM 잔액). 남의 대기줄을 둘러싼 재시도는 없습니다. 요청은 보장된 처리량으로 나갑니다. 참고로 GRAM은 이름이 바뀐 Toncoin이며(개명은 2026년 6월에 있었습니다), 네트워크는 여전히 TON입니다.

무료 Hobby 키(60 요청/분)는 로그인 직후 바로, 카드 없이 발급됩니다. 그다음은 성장에 맞춰, Pro는 월 $29에 300 요청/분, Scale은 월 $199에 1200 요청/분입니다. 중요한 디테일 하나: 모든 요금제에서 TONNode의 16개 도구를 전부 쓸 수 있습니다. 여러분이 돈을 내는 대상은 기능이 아니라 처리량입니다.

전용 라이트서버는 self-serve가 아니라 문의 기반입니다

hosted 요금제로도 부족해서 전용(single-tenant) 라이트서버, 즉 이웃 없이 오직 여러분의 트래픽만 받는 노드가 필요할 때가 있습니다. 그런 선택지는 있습니다. 다만 정직하게 말하면 이건 셀프서비스가 아닙니다. 대시보드에 "single-tenant 켜기" 버튼 같은 건 없고, 수동으로 처리됩니다. 저희에게 연락 주시면 부하와 구성을 함께 논의합니다.

히스토리 깊이에 대해서도 정직한 단서를 하나 답니다. TONNode의 아카이브 노드는 현재 동기화 중이며 아직 요청을 처리하지 않습니다. "아카이브 깊이"는 로드맵의 항목이지 완성된 기능이 아닙니다. 전 기간에 걸친 깊은 히스토리가 오늘 당장 반드시 필요하다면 그건 따로 계획하십시오. 무엇이 이미 준비됐고 무엇이 계획인지는 로드맵에 있습니다.

요약

• not ready = 노드가 동기화되지 않았다는 뜻입니다. 마스터체인이 shard보다 앞서 있고, 최신 shard 블록에 있는 계정 상태는 아직 확인할 수 없습니다.
• 글로벌 config의 공개 라이트서버는 공용이고 한도가 걸려 있습니다. not ready, ADNL 타임아웃, 깊은 히스토리 부재가 따라옵니다. toncenter/tonapi의 HTTP 429와 혼동하지 마십시오. 계층이 다릅니다.
• 클라이언트 쪽 처방(백오프 재시도, 엔드포인트 로테이션, 타임아웃)은 오류 빈도를 낮추지만 원인을 없애지는 못합니다.
• get_masterchain_info는 여러분의 healthcheck입니다. 노드가 마스터체인 헤드 자체를 못 따라잡았을 때만 not ready로 빨간불이 들어옵니다.
• 진짜 치료법은 공용 자원을 떠나 보장된 처리량으로 옮겨가는 것입니다.

무료 Hobby hosted 키를 받고 공용 노드에서 "not ready"에 시달리는 일을 끝내십시오 → tonnode.io/dashboard?plan=hobby

부하가 커지면 그다음은 요금제와 로드맵입니다.