Documentación de El libro de Sibuna 1.0.0-beta.3
Idioma: Español
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
En esta página

Parte VII: El motor de prueba de trabajo del navegador

Examinamos el módulo WebAssembly que compila el propio crate verificador del servidor, el protocolo del Web Worker, los probadores JavaScript de respaldo y la página intermedia.

Una fuente, dos destinos

Integración en la compilación

El solucionador del navegador se compila a partir de las mismas fuentes con las que verifica el servidor. cmd/sibuna-pow-wasm es un crate de biblioteca no_std de tipo cdylib, compilado para wasm32-unknown-unknown, cuyas únicas dependencias son los crates del workspace sibuna-pow y sibuna-crypto:

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

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

# Cargo.toml (raíz del workspace): el módulo se compila para ocupar poco
[profile.release.package.sibuna-pow-wasm]
opt-level = "z"
debug = false
strip = true

El daemon integra el módulo. Su script de compilación (cmd/sibuna/build.rs) ejecuta un cargo rustc -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm anidado en el directorio de destino del workspace (target/wasm32-unknown-unknown/wasm/). La compilación anidada solo bloquea los directorios del perfil wasm, así que nunca espera a la compilación externa. El enlazado final recibe --compress-relocations. El script comprueba que el resultado empieza por los bytes mágicos de WebAssembly y lo copia al directorio de salida de la compilación. SIBUNA_POW_WASM=<path> integra en su lugar un módulo precompilado, para compilaciones sin el destino WebAssembly. Después, el daemon incluye los bytes en su binario:

/// El solucionador del navegador, compilado por `build.rs` desde
/// `cmd/sibuna-pow-wasm`.
pub const WASM_SOLVER: &[u8] =
    include_bytes!(concat!(env!("OUT_DIR"), "/sibuna-pow.wasm"));
/// El Web Worker del solucionador.
pub const WORKER_JS: &str = include_str!("../../../web/worker.js");

No hay una segunda implementación que pueda divergir. El daemon sirve el módulo en /__sibuna/wasm/sibuna-pow.wasm con una cabecera de caché de una hora (Cache-Control: public, max-age=3600). Compilado con el perfil anterior, el módulo ocupa 14.744 bytes con ambos niveles (wasm_bytes en benchmarks/results/primitives-latest.json).

Exportaciones

El módulo exporta seis funciones, y el script del worker las llama por su nombre:

Exportación Función
sibuna_get_buffer_ptr() / sibuna_get_buffer_len() Búfer de entrada de 256 bytes en el que el worker escribe la cadena del desafío
sibuna_solve_step(ptr, len, bits, start, max_steps) Hashcash: prueba max_steps nonces a partir de start; devuelve el nonce o el centinela con todos los bits a uno
sibuna_solve_sha256(ptr, len, bits) Hashcash en un solo lote desde el nonce 0 (sibuna_solve_step con u32::MAX pasos)
sibuna_posw_solve(len, depth, challenges) Trabajo secuencial: ejecuta el probador sobre el búfer y devuelve la longitud de la prueba, o 0 si los argumentos no son válidos
sibuna_posw_proof_ptr() Inicio de los bytes de la prueba en el espacio de trabajo del probador

El espacio de trabajo del probador (los niveles superiores retenidos, la pila de nodos hermanos y la prueba) es una región estática de unos 92 KiB; no se enlaza ningún asignador y el módulo no tiene importaciones. Workspace::new es una const fn, así que la variable estática solo ocupa memoria puesta a cero, no datos inicializados dentro del módulo.

#[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: quien llama garantiza `challenge_len` bytes legibles en
        // `challenge_ptr` que no cambian mientras dura la llamada.
        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)
}

Las exportaciones son la frontera FFI (de funciones externas) del crate y el único lugar donde hay código unsafe. El búfer de entrada y el espacio de trabajo del probador son variables estáticas dentro de un ExportCell, un envoltorio de UnsafeCell declarado Sync con un motivo explícito: una instancia WebAssembly sin memoria compartida ejecuta un solo hilo, y cada exportación crea sus referencias, las usa y las suelta antes de volver, así que nunca hay más de una referencia viva a una celda. En el host, donde las pruebas llaman directamente a las exportaciones, un mutex que solo existe en las pruebas las serializa. Un pánico provoca una trampa (la instrucción unreachable) en lugar de formatear un mensaje, lo que mantiene el módulo libre de código de formateo y de importaciones; los pánicos son inalcanzables por construcción, porque las funciones de sibuna-pow son totales y nunca entran en pánico.

Hash previo del prefijo

El bucle interno de Hashcash absorbe el desafío y los dos puntos una sola vez y clona el estado SHA-256 para cada nonce, de modo que cada candidato cuesta una compresión en lugar de dos. La búsqueda es sibuna_pow::hashcash::Search, compartida por el módulo del navegador y el solucionador nativo de referencia:

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(); // copia del prefijo absorbido
    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
}

El estado del hasher es un valor simple de unos 110 bytes, así que clonarlo es barato. El probador de trabajo secuencial usa el mismo truco, con el enunciado \(\chi\) absorbido una vez en base_hasher y clonado para cada nodo, y ahora el verificador también: deriva cada hoja desafiada de un estado que ya ha absorbido el enunciado una vez, lo que ahorra \(t\) compresiones en la verificación con los mismos resúmenes.

En el servidor, la función de compresión usa las extensiones SHA de x86-64 o las instrucciones SHA-2 de ARMv8, detectadas en tiempo de ejecución. En el navegador no existen esas instrucciones, y el solucionador pasa casi todo su tiempo en la función de compresión portable (crates/crypto/src/sha256/portable.rs). Esa función está escrita para WebAssembly: las 64 rondas están desenrolladas, la expansión del mensaje ocupa una ventana de 16 palabras en la que cada ronda a partir de la 16 sobrescribe la palabra que ya no necesita, y las ocho variables de trabajo se renombran de una ronda a otra en lugar de desplazarse:

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);
    // ... rondas 16 a 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);
    }
}

/// Devuelve W(i) de la expansión; desde la ronda 16 la calcula in situ.
#[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]
}

Cada eight_rounds! es una vuelta completa de los nombres de las variables: la macro los pasa rotados una posición por ronda, de modo que una ronda escribe solo dos de ellos y nunca mueve los otros seis. Con un índice de ronda literal, cada posición de la expansión es una constante, y el bloque entero se convierte en código lineal cuyos valores permanecen en variables locales de WebAssembly. Esta disposición es aproximadamente un 20% más rápida en V8 que una expansión de 64 palabras con un bucle sin desenrollar, y aproximadamente un 14% más rápida en ejecución nativa (medido sobre la implementación en Rust, octubre de 2026).

El protocolo del worker

La página envía un mensaje a web/worker.js y recibe mensajes de progreso, de respaldo y de resultado:

// página -> worker
{ challenge: spec.id, algorithm: spec.algorithm, difficulty: spec.difficulty,
    challenges: spec.challenges }

// worker -> página
{ 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: '...' }

El worker prueba primero WebAssembly y recurre a JavaScript puro cuando WebAssembly no existe, está bloqueado por una política o no consigue instanciarse. Los probadores JavaScript reproducen etiqueta por etiqueta el probador Rust de sibuna-pow y producen una salida idéntica byte a byte. Las pruebas fijan nonces y pruebas concretos para ambos niveles, y SID 0010 exige que el solucionador funcione en un navegador sin interfaz gráfica tanto con WebAssembly como con el respaldo JavaScript. Los probadores JavaScript son mucho más lentos, pero garantizan que cualquier navegador pueda superar el desafío.

Calibración

No elijas una dificultad a partir del tiempo medio de resolución de un portátil. Hashcash tiene una cola geométrica; los relojes del navegador incluyen planificación, estado térmico, arranque y compilación. Una calibración de despliegue debe registrar la versión del navegador, el dispositivo, el algoritmo, los parámetros y una distribución de resoluciones repetidas. Mantén la descarga y compilación del módulo separadas del cálculo de hashes en régimen estable.

Las mediciones de primitivas nativas del repositorio no demuestran ningún tiempo de resolución que pueda prometerse en un teléfono o un navegador. Un módulo WASM puede ejecutar la misma aritmética con costes distintos de arranque, ejecución y memoria: en ejecución nativa, el servidor calcula hashes con SHA-NI, mientras que el navegador ejecuta la función de compresión portable descrita arriba. Los mensajes del worker forman la frontera en la que esos costes pueden medirse sin añadir un temporizador al manejador de peticiones del servidor.

La página intermedia

La página (web/challenge.html, integrada en el daemon) es un único archivo HTML con una tarjeta, una barra de progreso indeterminada y una línea de estado. Pide el desafío para su propia ubicación (?path=), lanza el worker, envía la solución con fetch y recarga si tiene éxito; las llamadas fetch se reintentan con espera exponencial con variación aleatoria, y una respuesta de verificación 4xx se muestra con su título de diagnóstico. La Content-Security-Policy de la página admite exactamente un script, el bloque del solucionador, por su hash SHA-256, que el daemon calcula una vez a partir de la página integrada. Un enlace honeypot fuera de pantalla (/__sibuna/honeypot) es invisible para las personas y para los navegadores que ejecutan scripts; los rastreadores ciegos que siguen cada href se bloquean a sí mismos.