Sibuna 기술 안내서 1.0.0-beta.3 문서
언어: 한국어
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
이 페이지의 내용

제IV부: Sibuna 프로토콜

구현된 그대로의 전송 프로토콜을 명세합니다. 중간 페이지 왕복, 상태 없는 챌린지 레코드, 두 가지 풀이 형식, 검증 순서, 일회 사용 강제, 세션 쿠키를 다룹니다.

챌린지 왕복

여덟 단계의 순환입니다. 브라우저 탐색, 중간 페이지(HTTP 200), GET /__sibuna/challenge.json?need=, 상태 없는 id(페이로드 + 태그), WASM 또는 JS 증명자로 푸는 Web Worker, nonce나 증명을 담은 POST /__sibuna/verify, 검증과 사용 완료 집합 기록과 MAC 토큰 발급, Set-Cookie 후 다시 불러오기를 거쳐 세션을 가지고 탐색으로 돌아옵니다.
그림 5 챌린지 왕복. 왼쪽 단계는 브라우저에서, 오른쪽 단계는 Sibuna에서 실행됩니다.
  1. 유효한 세션이 없는 탐색 요청은 정책 엔진에 도달해 CHALLENGE로 분류됩니다. 요청이 text/html을 받아들이므로 데몬은 중간 페이지와 X-Sibuna-Status: CHALLENGE 헤더를 담아 200으로 응답합니다. HTML을 받아들이지 않는 API 클라이언트는 바로 가져올 수 있는 challenge URL이 담긴 JSON 본문과 함께 401을 받습니다. 어느 쪽이든 응답에는 요구 티켓이 담깁니다. 이 결정이 요구하는 챌린지(알고리즘, 작업 비트, 개방 수)와 규칙의 해시를, 이 클라이언트 전용으로 도출한 키 아래 키 기반 BLAKE3 태그로 봉인한 것이며, 챌린지 수명 한 번 동안 유효합니다.

  2. 중간 페이지는 GET /__sibuna/challenge.json?path=<original URL>&need=<ticket>을 가져옵니다. 유효한 티켓이 있으면 티켓이 챌린지를 결정합니다. 작업량은 그것을 요구한 결정으로 고정되며, 보고된 URL과 이 가져오기 요청 자체의 헤더로 다시 계산하지 않습니다. 이 헤더(Accept, Sec-Fetch-*)는 탐색 요청의 헤더와 다르기 때문입니다. 유효한 티켓이 없으면(URL을 무시하는 API 클라이언트, 수명이 지나도록 열어 둔 페이지) 서버는 보고된 URL을 평가합니다. URL은 요청 줄을 읽는 것과 같은 함수로 경로와 쿼리로 나누고, 경로는 요청 허용이 쓰는 정규형으로 바꿉니다(SID 0009). 8 KiB보다 긴 URL은 잘라 내지 않고 414로 거부하며, 정규형이 없는 경로는 400으로 거부합니다. 티켓은 참고용일 뿐입니다. 요청 허용은 여전히 세션의 작업 수준을 확인하므로, 재전송하거나 위조한 티켓은 그 보유자에게 작업 비용만 지울 수 있습니다.

  3. 응답은 챌린지 레코드입니다.

    {"id":"AQEND...70 chars","algorithm":"posw","difficulty":13,"challenges":16,"expires_at":1757241234}
    

    hashcash에서는 difficulty가 비트 수이고 challenges는 0입니다.

  4. Web Worker가 WebAssembly 모듈로, WebAssembly를 쓸 수 없으면 JavaScript 증명자로(제VII부) 이를 풀고, 다음 둘 중 하나를

    {"challenge_id":"...","nonce":"90766"}
    

    또는

    {"challenge_id":"...","proof":"<base64url, 32(1 + t(n+1))바이트>"}
    

    POST /__sibuna/verify로 보냅니다.

  5. 성공하면 서버는 Set-Cookie 헤더와 함께 200 {"status":"ok"}로 응답하고, 페이지는 원래 위치를 다시 불러옵니다. 이후의 모든 요청은 쿠키를 함께 보내며 정책 평가 전에 허용됩니다.

상태 없는 챌린지 레코드

pub fn create_challenge_with_spec(
    &self,
    client_ip: &[u8],
    user_agent: &[u8],
    now: u64,
    spec: ChallengeSpec,
    rule_hash: u64,
) -> Challenge {
    self.adaptive.observe(now.saturating_mul(1000));
    let effective = ChallengeSpec {
        difficulty: spec.difficulty.saturating_add(self.adaptive.bump()),
        ..spec
    };
    let fingerprint = self.fingerprint(client_ip, user_agent);
    let difficulty = effective.parameter();
    let challenges = match effective.algorithm {
        Algorithm::Hashcash => 0,
        Algorithm::Posw => effective.posw_challenges,
    };

    let mut payload = [0u8; ID_PAYLOAD_LEN];
    payload[0] = ID_VERSION;
    payload[1] = effective.algorithm.to_byte();
    payload[2] = difficulty;
    payload[3] = challenges;
    payload[4..12].copy_from_slice(&now.to_le_bytes());
    payload[12..20].copy_from_slice(&fingerprint.to_le_bytes());
    payload[20..28].copy_from_slice(&self.next_nonce(now, fingerprint).to_le_bytes());
    payload[28..36].copy_from_slice(&rule_hash.to_le_bytes());
    let mut raw = [0u8; ID_RAW_LEN];
    raw[..ID_PAYLOAD_LEN].copy_from_slice(&payload);
    raw[ID_PAYLOAD_LEN..].copy_from_slice(&self.challenge_tag(&payload));

    Challenge {
        id: encoded::encode(&raw),
        algorithm: effective.algorithm,
        difficulty,
        challenges,
        expires_at: now.saturating_add(u64::from(self.challenge_ttl)),
    }
}

식별자는 Encoded<70>입니다. 텍스트는 정확히 그 길이의 배열에 담기므로 챌린지를 발급할 때 할당이 일어나지 않습니다. ChallengeSpec::parameter는 작업 비트를 계층 고유의 단위로 바꿉니다. Hashcash 비트(최대 64) 또는 PoSW 깊이(difficulty - 3, 4에서 24 사이로 제한)입니다.

세 가지 세부 사항을 눈여겨볼 만합니다.

  • 적응형 난이도. 코디네이터는 챌린지 발급률의 지수 가중 이동 평균을 원자 변수 세 개에 유지합니다. 기준선인 초당 챌린지 50개를 넘으면 발급률이 두 배가 될 때마다 작업 비트가 하나씩 늘며, 최대 여섯 비트까지 늘어납니다. 폭주 트래픽은 지수적으로 더 많은 비용을 치르고, 조용한 트래픽은 기본 비용을 유지합니다.
  • nonce는 PRF 출력입니다. 챌린지 키를 키로 하여 카운터, 시계, 지문 위에서 계산합니다. 카운터 덕분에 유일하고 키 덕분에 예측할 수 없으므로, 공격자는 발급받지 않은 식별자에 대한 풀이를 미리 계산할 수 없습니다. 또한 핫 패스는 엔트로피를 얻으려고 운영체제를 호출하지 않습니다.
  • 난이도는 태그 안에 담겨 전달됩니다. 클라이언트는 레코드를 고쳐 난이도를 낮출 수 없습니다. 그렇게 하면 증명을 살펴보기도 전에 태그 검사가 실패합니다.

검증 순서와 일회 사용

pub fn verify_and_mint(
    &self,
    challenge_id: &[u8],
    solution: Solution<'_>,
    client_ip: &[u8],
    user_agent: &[u8],
    now: u64,
) -> Result<Verified, VerifyError> {
    let record = self.decode(challenge_id)?;
    let expires_at = record.issued_at.saturating_add(u64::from(self.challenge_ttl));
    if now > expires_at || record.issued_at > now.saturating_add(CLOCK_SKEW_SECONDS) {
        return Err(VerifyError::ChallengeExpired);
    }
    if record.fingerprint != self.fingerprint(client_ip, user_agent) {
        return Err(VerifyError::FingerprintMismatch);
    }
    check_solution(challenge_id, &record, solution)?;
    self.spent.mark_spent(&record.tag, expires_at, now).map_err(|error| match error {
        SpendError::DoubleSpend => VerifyError::DoubleSpendAttempt,
        SpendError::Full => VerifyError::StoreFull,
    })?;
    let work = WorkLevel {
        algorithm: record.algorithm.to_byte(),
        bits: record.algorithm.work_bits(record.difficulty),
    };
    Ok(Verified {
        token: self.mint_token(now, record.rule_hash, record.fingerprint, work),
        algorithm: record.algorithm,
        difficulty: record.difficulty,
        challenges: record.challenges,
        ttl_seconds: self.token_ttl,
    })
}

이 순서는 의도적입니다. 태그, 경과 시간, 바인딩은 상수 시간 검사로, 해시를 계산하기 전에 쓰레기 입력을 거부합니다. 틀린 증명이 챌린지를 소모해서는 안 되므로, 사용 완료 집합에는 check_solution이 성공한 뒤에만 씁니다. 같은 유효한 풀이를 검증한 두 스레드는 mark_spent에서 경쟁합니다. 샤드 락이 둘을 직렬화하므로 정확히 하나만 이기고, 다른 하나는 VerifyError::DoubleSpendAttempt를 받습니다. issued_at > now + 60 조건(CLOCK_SKEW_SECONDS는 60)은 시계가 1분 넘게 앞선 노드가 만든 레코드를 거부합니다. 그렇지 않으면 그런 레코드가 챌린지의 수명을 늘릴 수 있습니다.

오류는 Elm 스타일 진단(제X부)과 함께 400으로 클라이언트에 전달됩니다. 각 VerifyError는 sibuna_core::errors::ErrorKind로 변환되며, 그 설명이 응답 본문이 됩니다. 종단 간 테스트는 응답 본문의 DOUBLE SPEND, FINGERPRINT MISMATCH, WRONG SOLUTION TYPE, MALFORMED CHALLENGE를 확인합니다.