The Sibuna Book 1.0.0-beta.3 documentation
Language: English
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
On this page

Part IV: The Sibuna Protocol

We specify the wire protocol as implemented: the interstitial round trip, the stateless challenge record, both solution formats, verification order, single-use enforcement, and the session cookie.

The Challenge Round Trip

A loop of eight steps: browser navigation, interstitial (HTTP 200), GET /__sibuna/challenge.json?need=, stateless id (payload + tag), Web Worker solving with the WASM or JS prover, POST /__sibuna/verify with the nonce or proof, verify, spent set and mint MAC token, Set-Cookie then reload, and back to the navigation with a session.
Fig. 5 The challenge round trip. Steps on the left run in the browser, steps on the right in Sibuna.
  1. A navigation with no valid session reaches the policy engine and is classified CHALLENGE. Because the request accepts text/html, the daemon answers 200 with the interstitial page and the header X-Sibuna-Status: CHALLENGE; an API client that does not accept HTML receives 401 with a JSON body whose challenge URL is ready to fetch. Either way the response carries a requirement ticket: the challenge this decision demands (algorithm, work bits, openings) and the rule’s hash, sealed for this client with a keyed BLAKE3 tag under its own derived key and valid for one challenge lifetime.

  2. The interstitial fetches GET /__sibuna/challenge.json?path=<original URL>&need=<ticket>. A valid ticket decides the challenge: the work is fixed by the decision that demanded it, not recomputed from a reported URL and the fetch’s own headers, which differ from the navigation’s (Accept, Sec-Fetch-*). Without a valid ticket (an API client that ignores the URL, a page left open past the lifetime) the server evaluates the reported URL, split into path and query by the same function that reads the request line, with the path put in the normal form admission uses (SID 0009); a URL longer than 8 KiB is refused with 414, never truncated, and a path without a normal form with 400. The ticket is advisory: admission still checks the session’s work level, so a replayed or forged ticket can only cost its holder work.

  3. The response is the challenge record:

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

    For hashcash, difficulty is the bit count and challenges is 0.

  4. A Web Worker solves it with the WebAssembly module, or the JavaScript prover if WebAssembly is unavailable (Part VII), and posts either

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

    or

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

    to POST /__sibuna/verify.

  5. On success the server answers 200 {"status":"ok"} with a Set-Cookie header, and the page reloads its original location. Every later request carries the cookie and is admitted before policy evaluation.

The Stateless Challenge Record

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)),
    }
}

The identifier is an Encoded<70>: the text lives in an array of exactly its length, so issuing a challenge never allocates. ChallengeSpec::parameter maps work bits to the tier’s own unit, Hashcash bits (at most 64) or PoSW depth (difficulty - 3, clamped to 4 through 24).

Three details deserve attention:

  • Adaptive difficulty. The coordinator keeps an exponentially weighted moving average of the challenge issue rate in three atomics. Above a baseline of 50 challenges per second, each doubling of the rate adds one work bit, capped at six. A flood pays exponentially more while quiet traffic keeps the base cost.
  • The nonce is a PRF output, keyed by the challenge key over a counter, the clock, and the fingerprint. It is unique (counter) and unpredictable (key), so an adversary cannot precompute solutions for identifiers it has not been issued, and the hot path never calls into the operating system for entropy.
  • Difficulty travels inside the tag. A client cannot lower the difficulty by editing the record: the tag would fail before any proof is examined.

Verification Order and Single Use

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,
    })
}

The order is deliberate. Tag, age, and binding are constant-time checks that reject garbage before any hashing. A wrong proof must not consume the challenge, so the spent set is written only after check_solution succeeds. Two threads that both verify the same valid solution race on mark_spent; the shard lock serialises them, exactly one wins, and the other receives VerifyError::DoubleSpendAttempt. The clause issued_at > now + 60 (CLOCK_SKEW_SECONDS is 60) rejects records minted by a node whose clock runs ahead by more than a minute, which would otherwise extend a challenge’s life.

Errors surface to the client as 400 with an Elm-style diagnostic (Part X): each VerifyError converts into sibuna_core::errors::ErrorKind, whose explanation is the response body. The end-to-end tests assert on DOUBLE SPEND, FINGERPRINT MISMATCH, WRONG SOLUTION TYPE, and MALFORMED CHALLENGE in the response body.