RAILGUN 서비스 상태 이력 API

서비스 상태 API는 "Anon의 모니터가 지금 무엇을 보고 있는가?"에 답합니다. 이 엔드포인트는 "지난 2주 동안 무엇을 보았는가?"에 답합니다. 실시간 보고서에 나오는 모든 서비스와 체인에 대해, 최대 14일 동안 5분 버킷마다 문자 하나씩과, 최근 24시간·7일·14일의 가동률을 반환합니다. 상태 페이지의 막대 차트를 그리기에 충분합니다. 누구나 읽을 수 있습니다. API 키도 계정도 필요하지 않습니다.

GET https://api.anon.inc/api/v1/railgun/liveness/history

이것은 Anon 자체 모니터가 한 곳에서 본 관점입니다. Railgun 공식 상태가 아니며 Railgun 자체를 측정한 값도 아닙니다. 모든 문자는 Anon의 모니터가 게시한 상태입니다. 한계에 이 데이터로 알 수 없는 내용을 정리해 두었습니다.

베타: 이 API는 베타이며, 실시간 엔드포인트와 같은 수준의 약속을 합니다. 필드, 값, 응답의 형태는 예고 없이 바뀔 수 있습니다. 알 수 없는 필드와 값은 무시하도록 클라이언트를 작성하십시오. 베타 상태를 참고하십시오.

빠른 시작

curl -i https://api.anon.inc/api/v1/railgun/liveness/history

응답에는 이력 데이터와 캐시 헤더가 들어 있습니다.

HTTP/2 200
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=120, stale-while-revalidate=60, stale-if-error=300
etag: "5b3f0c9a1d7e4426"
access-control-allow-origin: *
access-control-expose-headers: ETag

ETag를 If-None-Match와 함께 다시 보내면 변경 여부를 물을 수 있습니다. 바뀐 것이 없으면 본문 없이 304 Not Modified가 돌아옵니다.

curl -i https://api.anon.inc/api/v1/railgun/liveness/history \
  -H 'If-None-Match: "5b3f0c9a1d7e4426"'

쿼리 매개변수는 없습니다. 요청할 때마다 저장된 이력 전체가 반환되며, 문자열 대부분이 같은 문자의 반복이라 압축하면 몇 KB에 불과합니다.

작은 TypeScript 클라이언트입니다. 한 행을 읽어 버킷을 정해진 개수의 막대로 줄이고, 가동률을 서식화합니다. null 가동률은 100%가 아니라 "데이터 없음"으로 표시하며, 알 수 없는 문자는 데이터 없음으로 취급합니다.

type Uptime = Record<"24h" | "7d" | "14d", number | null>;

interface HistoryRow {
  service: string;
  chainId: number | null; // null for waku
  buckets: string; // one character per bucket, oldest first
  uptime: Uptime;
}

interface History {
  schemaVersion: number;
  generatedAt: string;
  bucketSeconds: number;
  retentionDays: number;
  from: string;
  to: string;
  rows: HistoryRow[];
}

const res = await fetch("https://api.anon.inc/api/v1/railgun/liveness/history", {
  headers: { Accept: "application/json" },
  signal: AbortSignal.timeout(8000),
});
if (!res.ok) throw new Error(`liveness history: HTTP ${res.status}`);
const report: History = await res.json();
if (report.schemaVersion !== 1) throw new Error("liveness history: unknown schemaVersion");

// Worst known state wins. Anything else in a bar is only shown if nothing known is.
const SEVERITY: Record<string, number> = { c: 0, k: 1, d: 2, u: 3 };

function barState(chars: string): string {
  let worst = "";
  for (const ch of chars) {
    if (ch in SEVERITY && (worst === "" || SEVERITY[ch] > SEVERITY[worst])) worst = ch;
  }
  if (worst) return worst;
  if (chars.includes("?")) return "?"; // unknown: no evidence
  if (chars.includes(".")) return "."; // unmonitored
  return "-"; // no data, or a character this client does not know
}

// Split the buckets into `bars` groups of nearly equal size, oldest first. Fewer
// buckets than bars gives one bar per bucket.
function downsample(buckets: string, bars: number): string[] {
  const count = Math.min(bars, buckets.length);
  const out: string[] = [];
  for (let i = 0; i < count; i++) {
    const start = Math.floor((i * buckets.length) / count);
    const end = Math.floor(((i + 1) * buckets.length) / count);
    out.push(barState(buckets.slice(start, end)));
  }
  return out;
}

// The server rounds to 4 decimals, so this is exact. null means "not enough data",
// which is not the same as 0% or 100%.
function formatUptime(value: number | null | undefined): string {
  if (typeof value !== "number" || !(value >= 0 && value <= 1)) return "no data";
  return `${(Math.round(value * 10000) / 100).toFixed(2)}%`;
}

for (const row of report.rows) {
  const label = `${row.service} ${row.chainId ?? "-"}`;
  console.log(label, downsample(row.buckets, 90).join(""), formatUptime(row.uptime["14d"]));
}

행은 service와 chainId로 맞추고, 사용하지 않는 행은 무시하십시오. 행의 순서에 의존하지 마십시오.

엔드포인트

GET https://api.anon.inc/api/v1/railgun/liveness/history

• 인증도 매개변수도 없습니다. 쿼리 문자열은 무시됩니다.
• HEAD는 헤더만 반환합니다. OPTIONS는 CORS 사전 요청에 응답합니다.
• 본문은 application/json; charset=utf-8입니다.
• 응답 하나가 모든 체인의 모든 서비스를 포괄합니다. 한 번 가져와서 필터링하십시오.
• 행은 /api/v1/railgun/liveness의 실시간 보고서와 같은 행이며 순서도 같습니다. 현재 21개입니다. 각 서비스가 무엇인지는 서비스와 체인을 참고하십시오.

응답 예시

행 다섯 개로 줄인 이력이며, 값은 설명을 위한 것입니다. 두 시간만 담고 있는데, 엔드포인트가 기록을 시작한 직후에 반환하는 모습입니다. 실제 응답에는 모든 행이 나오며, buckets 문자열은 4033자까지 늘어납니다(이력의 길이).

{
  "schemaVersion": 1,
  "generatedAt": "2026-10-06T14:03:11.402Z",
  "bucketSeconds": 300,
  "retentionDays": 14,
  "from": "2026-10-06T12:00:00Z",
  "to": "2026-10-06T14:00:00Z",
  "rows": [
    {
      "service": "ppoi",
      "chainId": 1,
      "buckets": "cccccccccccccccckcccccccc",
      "uptime": { "24h": 0.96, "7d": 0.96, "14d": 0.96 }
    },
    {
      "service": "subsquid",
      "chainId": 137,
      "buckets": "cccccckkkkdddcccccccccccc",
      "uptime": { "24h": 0.72, "7d": 0.72, "14d": 0.72 }
    },
    {
      "service": "subsquid",
      "chainId": 11155111,
      "buckets": ".........................",
      "uptime": { "24h": null, "7d": null, "14d": null }
    },
    {
      "service": "broadcasters",
      "chainId": 137,
      "buckets": "cccccccccccccuccccccccccc",
      "uptime": { "24h": 0.96, "7d": 0.96, "14d": 0.96 }
    },
    {
      "service": "waku",
      "chainId": null,
      "buckets": "cccccc------ccccccccccccc",
      "uptime": { "24h": 1, "7d": 1, "14d": 1 }
    }
  ]
}

• from은 2026-10-06T12:00:00Z, to는 2026-10-06T14:00:00Z입니다. 간격이 24개이므로 모든 buckets 문자열은 25자이며, 버킷마다 한 글자씩 오래된 것부터 나옵니다. to는 마지막 버킷의 시작 시각이며, generatedAt(14:03) 시점에도 아직 채워지는 중이었습니다.
• ppoi 행에는 k 버킷이 하나 있습니다. 그 5분 버킷 중 적어도 1분 동안 서비스가 catching-up 상태였고, 그보다 나쁜 상태는 그만큼 오래 지속되지 않았습니다. 가동률은 알려진 25개 버킷 중 24개로 0.96입니다.
• Polygon(137)의 subsquid 행에는 k 버킷 네 개에 이어 d 버킷 세 개가 연속으로 있고, 그 뒤 회복합니다. 25개 버킷 중 18개가 c이므로 가동률은 0.72입니다.
• Sepolia의 subsquid 행은 전부 .입니다. 모니터링 대상이 아닙니다. 알려진 버킷이 12개 미만이므로 모든 가동률이 null입니다.
• broadcasters 행에는 u 버킷이 하나 있습니다. 그 5분 버킷 중 적어도 1분 동안 서비스가 unavailable 상태였습니다.
• waku 행에는 - 버킷이 여섯 개 있습니다. 모니터가 실행 중이 아니었거나 아무것도 기록하지 못했습니다. 이 버킷들은 가동률에서 제외되며, 알려진 19개 버킷 기준으로 가동률은 1입니다.
• 이력이 두 시간뿐이라 여기서는 세 가동률 값이 같습니다. 각 윈도우는 실제로 존재하는 데이터로 잘립니다.
• chainId는 유일한 공유 행인 waku에서 null입니다.

필드

이력

from과 to는 UTC이며 끝에 문자 그대로 Z가 붙고 소수 초는 없습니다. YYYY-MM-DDTHH:mm:ssZ 형식입니다. generatedAt은 실시간 보고서와 같이 밀리초 정밀도입니다.

모든 buckets 문자열의 길이는 (to − from) / bucketSeconds + 1자이며, 모든 행에서 같습니다.

행

Sepolia(11155111)는 테스트넷입니다. 실시간 보고서와 마찬가지로, 직접 계산하는 메인넷 수치에서는 제외하십시오.

문자

각 상태의 의미는 실시간 보고서와 같습니다. 상태를 참고하십시오. 이 집합은 늘어날 수 있습니다. 알 수 없는 문자는 해당 버킷에 한해 -로 취급하고, 그 행의 나머지는 그대로 사용하십시오.

?, ., -는 서로 다르면서 분명히 녹색이 아닌 방식으로 표시하십시오. 이 셋은 각각 근거 없음, 대상 외, 기록되지 않음이라는 서로 다른 뜻입니다.

버킷과 가동률의 계산 방식

버킷

모니터는 모든 행에 대해 약 30초마다 상태를 게시합니다. 이력은 이렇게 게시된 상태를 보관하며, 버킷의 문자는 그 5분 동안 그 행에 게시된 상태에서 정해집니다.

1. 알려진 상태, 즉 current, catching-up, degraded, unavailable을 고릅니다. 심각도는 u가 가장 높고 d, k, c 순으로 낮아집니다. 문자는 그 5분 동안 합계 적어도 1분 지속된 가장 나쁜 상태입니다. 그보다 나쁜 상태였던 시간도 여기에 합산됩니다. 예를 들어 degraded 30초와 unavailable 40초는 d가 됩니다. 재시작 같은 더 짧은 일시적 문제는 계산되지 않으며, 이때 버킷은 c로 표시됩니다.
2. 알려진 상태는 없고 unknown만 있으면 문자는 ?입니다.
3. unmonitored 상태만 있으면 문자는 .입니다.
4. 샘플이 전혀 없으면 문자는 -입니다.

따라서 u는 그 버킷 중 적어도 1분 동안 서비스가 unavailable이었다는 뜻이고, c는 current보다 나쁜 상태가 1분 동안 지속되지 않았다는 뜻입니다. 버킷은 평균이 아니라 지속된 가장 나쁜 상태를 나타냅니다. 마지막 버킷은 아직 채워지는 중이므로 끝날 때까지 문자가 바뀔 수 있습니다.

가동률

윈도우마다 가동률은 다음과 같습니다.

c / (c + k + d + u)

최근 24시간, 7일, 14일의 버킷을 대상으로 하며, 실제로 존재하는 이력으로 잘립니다. 결과는 소수 넷째 자리까지 반올림합니다.

• ?, ., - 버킷은 분자와 분모 양쪽에서 제외됩니다. 통과도 실패도 아닙니다.
• k는 d, u와 마찬가지로 가동률을 깎습니다. 따라잡는 중인 서비스는 가동 중으로 치지 않습니다.
• 윈도우에 알려진 버킷이 12개 미만이면(근거가 1시간 미만이면) 값은 null입니다. 전부 모니터링 대상이 아닌 행도 null입니다.
• null은 0도 1도 아닙니다. "데이터 없음"으로 표시하십시오.
• 값이 정확히 1이면 그 윈도우에서 알려진 버킷 중 c가 아닌 것이 없었다는 뜻입니다. 14일 동안 c가 아닌 버킷이 하나만 있어도 값은 최대 0.9998입니다.

buckets로 직접 윈도우를 계산하거나 서비스를 원하는 대로 조합할 수 있습니다. 직접 계산한 값은 윈도우 경계에서 서버 값과 조금 다를 수 있습니다.

이력의 길이

from은 모니터가 기록한 첫 번째 버킷이거나, 그보다 늦다면 14일 윈도우의 시작입니다. 이력은 이 기능이 출시된 날부터만 존재하며, 소급 채움은 없습니다. 그래서 문자열은 1자에서 시작해 5분마다 한 글자씩 늘어 최대 4033자가 되며, 처음 14일이 걸립니다. 그 뒤에는 윈도우가 이동합니다. 새 버킷이 시작될 때 가장 오래된 버킷이 빠집니다.

그때까지는 24h, 7d, 14d가 같은 짧은 기간을 가리킬 수 있고, 이력이 짧으면 7d와 14d가 null일 수도 있습니다. 뒷받침하는 데이터가 얼마나 되는지 밝히지 않은 채 수치에 "14일"이라고 표기하지 마십시오. from과 to를 비교하면 알 수 있습니다.

한계

• 관측 지점이 하나입니다. Anon의 인프라에서 실행되는 Anon의 모니터가, Anon이 사용하도록 설정된 서비스를 프로브합니다. 사용자가 보는 그 서비스의 모습은 다를 수 있습니다. 버킷은 사용자의 지갑이나 네트워크가 무엇을 보았을지를 알려 주지 않습니다.
• 모니터가 게시한 내용이며, Railgun을 측정한 값이 아닙니다. u 버킷은 모니터가 읽도록 설정된 서비스에서 연속 세 번 사용할 수 있는 응답을 받지 못했다는 뜻입니다. 다른 누구에게도 그 서비스가 중단되었다는 증거는 아닙니다. "안전하게 거래할 수 있음"을 뜻하는 신호도 아닙니다. 알려 주지 않는 것을 참고하십시오.
• 이력은 출시 시점부터 시작합니다. 처음 기록된 버킷보다 오래된 데이터는 없으며, 소급 채움도 없습니다. 짧은 이력은 완벽하다는 뜻이 아니라 짧다는 뜻입니다.
• 데이터 없음은 모니터링의 공백입니다. - 버킷은 장애도 통과도 아닙니다. 그 5분 동안 모니터가 실행 중이 아니었거나 아무것도 기록하지 않았다는 뜻이므로, 공백으로 표시하십시오. 가동률에서는 제외됩니다.
• 알 수 없음도 장애가 아닙니다. ?는 모니터에 근거가 없었다는 뜻입니다. 가동률에서는 제외됩니다.
• 14일뿐입니다. 그보다 오래된 버킷은 사라집니다. 더 긴 기록이 필요하면 응답을 직접 저장하십시오.
• 거칩니다. 5분 버킷은 그보다 짧은 일을 가립니다. 합계 1분 미만의 문제는 전혀 나타나지 않고, 1분 지속된 문제는 버킷 전체의 색을 바꿉니다. 가동률도 두 가지 모두를 그대로 이어받습니다.
• 베타. 실시간 엔드포인트와 마찬가지로 예고 없이 바뀔 수 있습니다. 베타 상태를 참고하십시오.

최신성과 캐싱

이력은 천천히 변합니다. 최신 버킷은 샘플이 도착하면서 바뀔 수 있고, 이력이 14일 길이가 된 뒤에는 5분마다 윈도우가 버킷 하나씩 앞으로 이동합니다. 응답에는 다음이 들어 있습니다.

Cache-Control: public, max-age=60, s-maxage=120, stale-while-revalidate=60, stale-if-error=300

얼마나 오래된 데이터일 수 있나요? generatedAt은 저장된 이력이 마지막으로 기록된 시각을 알려 줍니다. 여기에 더해, 엣지 사본은 사용자에게 도착할 때 몇 분 묵었을 수 있습니다. s-maxage가 최대 2분, stale-while-revalidate가 최대 1분이며, 브라우저에서는 최대 1분이 더해집니다. 이 엔드포인트로 서비스가 지금 가동 중인지를 판단하지 마십시오. 그럴 때는 실시간 엔드포인트를 사용하고 expiresAt을 읽으십시오.

1분에 한 번보다 자주 폴링하지 마십시오. 더 자주 폴링해도 캐시된 사본만 돌아옵니다. 차트를 보여 주는 페이지는 열릴 때 한 번 가져오고, 이후 화면이 보이는 상태에서 몇 분 뒤에 다시 가져오면 됩니다.

ETag와 304. ETag는 본문의 따옴표로 묶인 해시입니다. 모니터는 약 1분마다 이력을 다시 쓰고 generatedAt은 본문의 일부이므로, 바뀐 버킷이 없어도 generatedAt과 ETag는 약 1분마다 바뀝니다. 304는 주로 같은 1분 안에 재검증할 때 받게 됩니다. If-None-Match를 쓰면 바뀌지 않은 이력은 304로 끝납니다. 이 응답에는 ETag, Cache-Control, CORS 헤더가 있고 본문은 없습니다. 응답은 Vary: Origin을 보내지 않습니다. CDN은 Origin 요청 헤더 값마다 별도의 사본을 보관하며 쿼리 문자열은 무시합니다.

HTTP 상태 코드와 오류

HTTP 상태 코드로 분기하고, 메시지 텍스트로는 절대 분기하지 마십시오. API 자체의 오류는 {"error": "<message>"} 형태입니다. 게이트웨이의 404와 CDN의 429는 다른 본문을 사용합니다. 429는 Cloudflare의 text/plain 페이지입니다.

브라우저에서는 429를 읽을 수 없습니다. CDN의 429 페이지에는 Access-Control-Allow-Origin이 없으므로 브라우저가 이를 차단하고, fetch는 다른 네트워크 또는 CORS 실패와 마찬가지로 TypeError로 거부됩니다. 코드에서는 상태나 Retry-After를 볼 수 없습니다. 모든 네트워크 실패를 429나 503처럼 처리하십시오. 백오프하고, 마지막으로 받은 정상 이력을 generatedAt과 함께 계속 표시하십시오.

CORS

이력은 공개 데이터이고 호출자별 내용이 없으므로, 모든 응답이 모든 오리진을 허용합니다.

Access-Control-Allow-Credentials는 없습니다. Accept 헤더를 붙인 일반 fetch는 단순 요청이므로 사전 요청이 필요 없습니다. If-None-Match를 직접 설정하는 스크립트는 사전 요청이 필요하며, 엔드포인트는 자체 OPTIONS 사전 요청에 204로 응답합니다. 허용되는 메서드와 헤더는 실시간 엔드포인트와 같습니다.

공정 사용

실시간 엔드포인트와 같은 규칙이 적용됩니다. 키도 SLA도 없고, Cache-Control을 준수하고 ETag를 사용하며, 서버는 설명적인 User-Agent를 보내야 하고, 이 경로로 IP당 분당 약 120건을 넘는 요청에는 429가 올 수 있습니다. 429와 5xx가 오면 백오프하십시오.

또한 이 데이터는 천천히 변하므로 1분에 한 번보다 자주 폴링하지 말고, 사용자가 이를 보여 주는 화면을 열 때 가져오는 방식을 권장합니다. 사용자가 많다면 자체 서버에서 가져와 그곳에 캐시하십시오.

베타 상태

이 API는 베타이며, 약속의 수준은 실시간 엔드포인트와 같고 그보다 강하지 않습니다.

• 예고 없이 바뀔 수 있습니다. 필드, 문자, 윈도우, 응답의 형태는 예고 기간 없이 추가, 이름 변경, 타입 변경 또는 제거될 수 있으며, 지원 중단(deprecation)이나 종료(sunset) 절차도 약속하지 않습니다. 보관 기간, 버킷 길이, 가동률 윈도우는 현재의 값입니다.
• schemaVersion도 바뀔 수 있습니다. 아는 값이 아니라면, 업데이트할 때까지 이력을 읽을 수 없는 것으로 취급하십시오. JSON Schema는 느슨하게 작성되어 현재의 응답을 설명할 뿐, 약속이 아닙니다.
• 변경 기록. 변경은 최선을 다해 아래의 변경 내역에 기록합니다.

이를 견딜 수 있는 클라이언트를 작성하는 방법은 다음과 같습니다.

• 알 수 없는 필드는 무시하십시오. 이력, 각 행, uptime 등 모든 수준에서 그렇게 하십시오.
• 닫힌 집합에 의존하지 마십시오. 알 수 없는 버킷 문자는 해당 버킷에 한해 -로 취급하십시오. 사용하지 않는 service나 chainId의 행은 무시하십시오. 알 수 없는 uptime 키도 무시하십시오.
• 전체 이력이 아니라 행 하나만 실패시키십시오. 읽을 수 없는 행이 하나 있다고, 예를 들어 uptime이 없거나 buckets 문자열 길이가 맞지 않는다고 해서 다른 행까지 비워서는 안 됩니다.
• 길이를 하드코딩하지 마십시오. from, to, bucketSeconds를 사용하십시오.

변경 내역

2026-10-07

추가되었습니다. GET /api/v1/railgun/liveness/history는 실시간 보고서의 모든 행에 대해 최대 14일의 5분 버킷과 24시간·7일·14일 가동률을 반환합니다. schemaVersion 1, 베타입니다. 이력은 2026-10-07 01:55 UTC부터 기록되며 소급 채움은 없습니다.