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

제VII부: 브라우저 작업 증명 엔진

서버 자신의 검증자 crate를 컴파일한 WebAssembly 모듈, Web Worker 프로토콜, JavaScript 대체 증명자, 그리고 중간 페이지를 살펴봅니다.

소스 하나, 타깃 두 개

빌드 연결

브라우저 솔버는 서버가 검증에 쓰는 바로 그 소스를 컴파일합니다. cmd/sibuna-pow-wasm은 wasm32-unknown-unknown용으로 빌드하는 cdylib 유형의 no_std 라이브러리 crate이며, 의존성은 워크스페이스 crate인 sibuna-pow와 sibuna-crypto뿐입니다.

# cmd/sibuna-pow-wasm/Cargo.toml
[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
sibuna-crypto = { workspace = true }
sibuna-pow = { workspace = true }

# Cargo.toml(워크스페이스 루트): 모듈을 크기 우선으로 빌드합니다
[profile.release.package.sibuna-pow-wasm]
opt-level = "z"
debug = false
strip = true

데몬은 이 모듈을 내장합니다. 데몬의 빌드 스크립트(cmd/sibuna/build.rs)는 워크스페이스의 target 디렉터리(target/wasm32-unknown-unknown/wasm/)로 중첩된 cargo rustc -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm을 실행합니다. 중첩 빌드는 wasm 프로파일의 디렉터리만 잠그므로 바깥 빌드를 기다리지 않습니다. 최종 링크에는 --compress-relocations가 붙습니다. 스크립트는 결과가 WebAssembly 매직 바이트로 시작하는지 확인하고 빌드 출력 디렉터리로 복사합니다. WebAssembly 타깃이 없는 빌드에서는 SIBUNA_POW_WASM=<path>로 미리 빌드한 모듈을 대신 내장합니다. 그런 다음 데몬은 그 바이트를 바이너리에 포함합니다.

/// `build.rs`가 `cmd/sibuna-pow-wasm`에서 빌드한 브라우저 솔버.
pub const WASM_SOLVER: &[u8] =
    include_bytes!(concat!(env!("OUT_DIR"), "/sibuna-pow.wasm"));
/// 솔버의 Web Worker.
pub const WORKER_JS: &str = include_str!("../../../web/worker.js");

어긋날 수 있는 두 번째 구현이 없습니다. 모듈은 데몬이 /__sibuna/wasm/sibuna-pow.wasm에서 1시간 캐시 헤더(Cache-Control: public, max-age=3600)와 함께 제공합니다. 위 프로파일로 빌드한 모듈은 두 계층을 모두 포함해 14,744바이트입니다(benchmarks/results/primitives-latest.json의 wasm_bytes).

내보낸 함수

모듈은 함수 여섯 개를 내보내며, 워커 스크립트는 이름으로 이 함수들을 호출합니다.

내보낸 함수 용도
sibuna_get_buffer_ptr() / sibuna_get_buffer_len() 워커가 챌린지 문자열을 써 넣는 256바이트 입력 버퍼
sibuna_solve_step(ptr, len, bits, start, max_steps) Hashcash: start부터 nonce max_steps개를 탐색하고, nonce 또는 모든 비트가 1인 표식 값을 반환합니다
sibuna_solve_sha256(ptr, len, bits) nonce 0부터 한 번의 배치로 실행하는 Hashcash(u32::MAX 단계로 호출한 sibuna_solve_step)
sibuna_posw_solve(len, depth, challenges) 순차 작업: 버퍼에 대해 증명자를 실행하고 증명 길이를 반환하며, 인수가 잘못되면 0을 반환합니다
sibuna_posw_proof_ptr() 증명자 작업 공간 안에서 증명 바이트가 시작하는 위치

증명자의 작업 공간, 즉 보관하는 상위 레벨, 형제 스택, 증명은 약 92 KiB의 정적 영역입니다. 할당자는 링크되지 않으며 모듈에는 가져오기(import)가 없습니다. Workspace::new는 const fn이므로 이 정적 영역은 모듈 안의 초기화된 데이터가 아니라 0으로 채운 메모리만 차지합니다.

#[unsafe(no_mangle)]
pub unsafe extern "C" fn sibuna_solve_step(
    challenge_ptr: *const u8,
    challenge_len: usize,
    difficulty_bits: u32,
    start_nonce: u64,
    max_steps: u32,
) -> u64 {
    let challenge: &[u8] = if challenge_len == 0 {
        &[]
    } else {
        // SAFETY: 호출자는 `challenge_ptr`에 읽을 수 있는 `challenge_len`바이트가 있고
        // 그 바이트가 호출이 끝날 때까지 바뀌지 않음을 보장합니다.
        unsafe { core::slice::from_raw_parts(challenge_ptr, challenge_len) }
    };
    Search::new(challenge)
        .find(difficulty_bits, start_nonce, u64::from(max_steps))
        .unwrap_or(EXHAUSTED)
}

내보낸 함수들은 이 crate의 외부 함수 경계이며, unsafe 코드가 있는 유일한 곳입니다. 입력 버퍼와 증명자 작업 공간은 ExportCell 안의 정적 변수입니다. 이 래퍼는 UnsafeCell을 감싸며, 이유를 밝힌 채 Sync로 선언되어 있습니다. 공유 메모리가 없는 WebAssembly 인스턴스는 스레드 하나로 실행되며, 각 내보내기 함수는 참조를 만들고 사용한 뒤 반환하기 전에 버리므로, 셀을 가리키는 참조는 언제나 많아야 하나만 살아 있습니다. 테스트가 내보내기 함수를 직접 호출하는 호스트에서는 테스트 전용 뮤텍스가 호출을 직렬화합니다. 패닉은 메시지를 포맷하지 않고 트랩(unreachable 명령어)으로 끝나므로, 모듈에는 포맷 코드와 가져오기가 없습니다. sibuna-pow의 함수는 모든 입력에 대해 정의된 전함수(total function)이고 결코 패닉하지 않으므로, 구조상 패닉에는 도달할 수 없습니다.

접두사 사전 해싱

Hashcash 안쪽 루프는 챌린지와 콜론을 한 번만 흡수하고 nonce마다 SHA-256 상태를 복제하므로, 후보 하나의 비용은 압축 두 번이 아니라 한 번입니다. 탐색은 브라우저 모듈과 네이티브 참조 솔버가 공유하는 sibuna_pow::hashcash::Search입니다.

pub fn new(challenge: &[u8]) -> Self {
    let mut prefix = Sha256::new();
    prefix.update(challenge);
    prefix.update(b":");
    Self { prefix }
}

pub fn digest(&self, nonce: u64) -> Digest {
    let mut buf = [0u8; NONCE_DIGITS_MAX];
    let mut hasher = self.prefix.clone(); // 흡수한 접두사를 값으로 복사
    hasher.update(format_decimal(nonce, &mut buf));
    hasher.finalize()
}

pub fn find(&self, bits: u32, start: u64, steps: u64) -> Option<u64> {
    let mut nonce = start;
    for _ in 0..steps {
        if meets_bits(&self.digest(nonce), bits) {
            return Some(nonce);
        }
        nonce = nonce.wrapping_add(1);
    }
    None
}

해셔 상태는 약 110바이트의 평범한 값이므로 복제 비용이 작습니다. 순차 작업 증명자도 같은 기법을 써서 명제 \(\chi\)를 base_hasher에 한 번 흡수하고 노드마다 복제합니다. 이제 검증자도 그렇게 합니다. 명제를 한 번 흡수한 상태에서 챌린지로 지정된 잎을 각각 도출하므로, 같은 다이제스트를 얻으면서 검증에서 압축 \(t\)번을 아낍니다.

서버에서는 압축 함수가 실행 시점에 감지한 x86-64 SHA 확장이나 ARMv8 SHA-2 명령어를 사용합니다. 브라우저에는 그런 명령어가 없으므로 솔버는 거의 모든 시간을 이식 가능한 압축 함수(crates/crypto/src/sha256/portable.rs)에서 보냅니다. 이 함수는 WebAssembly를 위해 작성되었습니다. 64라운드를 펼쳐 놓았고, 메시지 스케줄은 16워드 창에 두어 16라운드부터는 각 라운드가 더는 필요 없는 워드를 덮어쓰며, 작업 변수 여덟 개는 옮기는 대신 라운드마다 이름을 바꿉니다.

fn compress_block(state: &mut State, block: &Block) {
    let mut w = [0u32; 16];
    for (word, bytes) in w.iter_mut().zip(block.as_chunks::<4>().0) {
        *word = u32::from_be_bytes(*bytes);
    }
    let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut h] = *state;
    eight_rounds!(w, 0, a, b, c, d, e, f, g, h);
    eight_rounds!(w, 8, a, b, c, d, e, f, g, h);
    // ... 라운드 16부터 55까지
    eight_rounds!(w, 56, a, b, c, d, e, f, g, h);
    for (word, value) in state.iter_mut().zip([a, b, c, d, e, f, g, h]) {
        *word = word.wrapping_add(value);
    }
}

/// 스케줄 워드 W(i)를 반환합니다. 라운드 16부터는 제자리에서 계산합니다.
#[inline(always)]
fn schedule(w: &mut [u32; 16], i: usize) -> u32 {
    if i >= 16 {
        let w15 = w[(i + 1) % 16];
        let w2 = w[(i + 14) % 16];
        let s0 = w15.rotate_right(7) ^ w15.rotate_right(18) ^ (w15 >> 3);
        let s1 = w2.rotate_right(17) ^ w2.rotate_right(19) ^ (w2 >> 10);
        w[i % 16] = w[i % 16]
            .wrapping_add(s0)
            .wrapping_add(w[(i + 9) % 16])
            .wrapping_add(s1);
    }
    w[i % 16]
}

eight_rounds! 하나는 변수 이름을 한 바퀴 완전히 돌립니다. 매크로는 라운드마다 이름을 한 자리씩 회전시켜 넘기므로, 한 라운드는 두 변수에만 쓰고 나머지 여섯 개는 옮기지 않습니다. 라운드 인덱스가 리터럴이므로 모든 스케줄 위치가 상수가 되고, 블록 전체가 값이 WebAssembly 지역 변수에 머무는 직선 코드가 됩니다. 이 배치는 펼치지 않은 루프로 64워드 스케줄을 계산하는 방식보다 V8에서 약 20%, 네이티브에서 약 14% 빠릅니다(Rust 구현으로 측정, 2026년 10월).

워커 프로토콜

페이지는 web/worker.js에 메시지 하나를 보내고 진행, 대체, 결과 메시지를 받습니다.

// 페이지 -> 워커
{ challenge: spec.id, algorithm: spec.algorithm, difficulty: spec.difficulty,
    challenges: spec.challenges }

// 워커 -> 페이지
{ type: 'progress', iterations: 40000 }
{ type: 'fallback', message: 'Wasm unavailable; running JS prover' }
{ type: 'solved', challenge: spec.id, solution: { nonce: '90766' } }  // hashcash
{ type: 'solved', challenge: spec.id, solution: { proof: '<base64url>' } } // posw
{ type: 'error', message: '...' }

워커는 먼저 WebAssembly를 시도하고, WebAssembly가 없거나 정책으로 막혀 있거나 인스턴스 생성에 실패하면 순수 JavaScript로 대체합니다. JavaScript 증명자는 sibuna-pow의 Rust 증명자를 라벨 하나하나까지 그대로 따르며 바이트 단위로 동일한 출력을 냅니다. 테스트는 두 계층 모두에 대해 고정된 nonce와 증명을 확인하며, SID 0010은 솔버가 헤드리스 브라우저에서 WebAssembly로도, JavaScript 대체 경로로도 통과하도록 요구합니다. JavaScript 증명자는 훨씬 느리지만 모든 브라우저가 통과할 수 있음을 보장합니다.

보정

노트북 한 대의 평균 풀이 시간으로 난이도를 고르지 마세요. Hashcash에는 기하 분포의 꼬리가 있고, 브라우저의 시간에는 스케줄링, 발열 상태, 시작과 컴파일 시간이 포함됩니다. 배포를 보정할 때는 브라우저 버전, 기기, 알고리즘, 매개변수, 그리고 반복 풀이의 분포를 기록해야 합니다. 모듈을 가져오고 컴파일하는 시간은 정상 상태의 해싱과 분리하세요.

저장소의 네이티브 기본 연산 측정은 휴대폰이나 브라우저의 풀이 시간을 약속하는 근거가 되지 않습니다. WASM 모듈은 같은 산술을 실행하면서도 시작, 실행, 메모리 비용이 다를 수 있습니다. 네이티브 서버는 SHA-NI로 해시하지만, 브라우저는 위의 이식 가능한 압축 함수를 실행합니다. 워커의 메시지는 서버의 요청 처리기에 타이머를 추가하지 않고도 이 비용을 측정할 수 있는 경계입니다.

중간 페이지

페이지(web/challenge.html, 데몬에 내장)는 카드, 진행률을 표시하지 않는 진행 막대, 상태 줄로 이루어진 HTML 파일 하나입니다. 자신의 위치에 대한 챌린지를 요청하고(?path=), 워커를 띄우고, fetch로 풀이를 보낸 뒤, 성공하면 다시 불러옵니다. fetch 호출은 지터를 넣은 지수 백오프로 재시도하며, 4xx 검증 응답은 진단 제목과 함께 표시됩니다. 페이지의 Content-Security-Policy는 정확히 스크립트 하나, 즉 솔버 블록만 SHA-256 해시로 허용하며, 데몬은 내장된 페이지에서 이 해시를 한 번 계산합니다. 화면 밖에 둔 허니팟 링크(/__sibuna/honeypot)는 사람에게도, 스크립트를 실행하는 브라우저에게도 보이지 않습니다. 모든 href를 따라가는 맹목적인 크롤러는 스스로 차단됩니다.