제IV부: Sibuna 프로토콜¶
구현된 그대로의 전송 프로토콜을 명세합니다. 중간 페이지 왕복, 상태 없는 챌린지 레코드, 두 가지 풀이 형식, 검증 순서, 일회 사용 강제, 세션 쿠키를 다룹니다.
챌린지 왕복¶
-
유효한 세션이 없는 탐색 요청은 정책 엔진에 도달해
CHALLENGE로 분류됩니다. 요청이text/html을 받아들이므로 데몬은 중간 페이지와X-Sibuna-Status: CHALLENGE헤더를 담아200으로 응답합니다. HTML을 받아들이지 않는 API 클라이언트는 바로 가져올 수 있는challengeURL이 담긴 JSON 본문과 함께401을 받습니다. 어느 쪽이든 응답에는 요구 티켓이 담깁니다. 이 결정이 요구하는 챌린지(알고리즘, 작업 비트, 개방 수)와 규칙의 해시를, 이 클라이언트 전용으로 도출한 키 아래 키 기반 BLAKE3 태그로 봉인한 것이며, 챌린지 수명 한 번 동안 유효합니다. -
중간 페이지는
GET /__sibuna/challenge.json?path=<original URL>&need=<ticket>을 가져옵니다. 유효한 티켓이 있으면 티켓이 챌린지를 결정합니다. 작업량은 그것을 요구한 결정으로 고정되며, 보고된 URL과 이 가져오기 요청 자체의 헤더로 다시 계산하지 않습니다. 이 헤더(Accept,Sec-Fetch-*)는 탐색 요청의 헤더와 다르기 때문입니다. 유효한 티켓이 없으면(URL을 무시하는 API 클라이언트, 수명이 지나도록 열어 둔 페이지) 서버는 보고된 URL을 평가합니다. URL은 요청 줄을 읽는 것과 같은 함수로 경로와 쿼리로 나누고, 경로는 요청 허용이 쓰는 정규형으로 바꿉니다(SID 0009). 8 KiB보다 긴 URL은 잘라 내지 않고414로 거부하며, 정규형이 없는 경로는400으로 거부합니다. 티켓은 참고용일 뿐입니다. 요청 허용은 여전히 세션의 작업 수준을 확인하므로, 재전송하거나 위조한 티켓은 그 보유자에게 작업 비용만 지울 수 있습니다. -
응답은 챌린지 레코드입니다.
{"id":"AQEND...70 chars","algorithm":"posw","difficulty":13,"challenges":16,"expires_at":1757241234}
hashcash에서는difficulty가 비트 수이고challenges는0입니다. -
Web Worker가 WebAssembly 모듈로, WebAssembly를 쓸 수 없으면 JavaScript 증명자로(제VII부) 이를 풀고, 다음 둘 중 하나를
{"challenge_id":"...","nonce":"90766"}
또는
{"challenge_id":"...","proof":"<base64url, 32(1 + t(n+1))바이트>"}
POST /__sibuna/verify로 보냅니다. -
성공하면 서버는
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를 확인합니다.