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 navigation with no valid session reaches the policy engine and is classified
CHALLENGE. Because the request acceptstext/html, the daemon answers200with the interstitial page and the headerX-Sibuna-Status: CHALLENGE; an API client that does not accept HTML receives401with a JSON body whosechallengeURL 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. -
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 with414, never truncated, and a path without a normal form with400. The ticket is advisory: admission still checks the session’s work level, so a replayed or forged ticket can only cost its holder work. -
The response is the challenge record:
{"id":"AQEND...70 chars","algorithm":"posw","difficulty":13,"challenges":16,"expires_at":1757241234}
For
hashcash,difficultyis the bit count andchallengesis0. -
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. -
On success the server answers
200 {"status":"ok"}with aSet-Cookieheader, 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.