Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xandrlabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

The alx_protocol_v1 Rust crate implements kb_hash_from_envelope with identical semantics to the TypeScript reference implementation in @alx/protocol. Like the Python implementation, its primary purpose is conformance verification: given the same envelope, it must produce the same kbHash. The crate is validated against the canonical test vectors in test-vectors/canonical/.
The Rust crate is for conformance verification. For building production integrations with ALX Protocol, use @alx/protocol (TypeScript), which is the primary SDK.

​
Requirements

  • Rust 2021 edition or later
  • Cargo

​
Adding the crate

Add the following to your Cargo.toml: 
[dependencies]
alx_protocol_v1 = { path = "implementations/rust" }

# Transitive dependencies used internally:
hex = "0.4"
serde_json = "1.0"
sha3 = "0.10"
If you are consuming the crate from within the alx-protocol repository, reference it by path as shown above. For external use, publish the crate to crates.io and reference it by version.

​
Running the conformance suite

cargo test --manifest-path implementations/rust/Cargo.toml
This replays every vector under test-vectors/canonical/ and the derivation vectors, asserting that kb_hash_from_envelope matches the expected kbHash in each expected.json file.

​
API

ExportDescription
kb_hash_from_envelope(envelope: &Value) -> Result<String, String>Derives kbHash: keccak256("KB_V1" + JCS(normalizedEnvelope)). Returns a 0x-prefixed hex string.
kb_hash_from_json(json: &str) -> Result<String, String>Parses a JSON string and calls kb_hash_from_envelope.
canonicalize_value(value: &Value) -> Result<String, String>RFC 8785-style (JCS) deterministic JSON serializer. Returns Err on null.
normalize_for_hash(envelope: &Value) -> Result<Value, String>Extracts hash-scoped fields and sorts sources deterministically.
KB_DOMAIN_PREFIXThe "KB_V1" constant prepended before hashing.

​
Example: computing kbHash in Rust

The following produces the same kbHash as the equivalent TypeScript call to kbHashFromEnvelope: 
use alx_protocol_v1::kb_hash_from_envelope;
use serde_json::{json, Value};

fn main() {
    let envelope: Value = json!({
        "type": "practice",
        "domain": "software.security",
        "sources": [],
        "tier": "open",
        "artifactHash": "0x5e71fc830e383453429f2b703db3eb456dc4a6bfd66b2a0fc7535330ab8b168a",
        "payload": {
            "type": "practice",
            "rationale": "Use constant-time comparison to prevent timing attacks on tokens.",
            "contexts": [],
            "failureModes": []
        }
    });

    let kb_hash = kb_hash_from_envelope(&envelope).expect("valid envelope");
    println!("{}", kb_hash);
    // 0x5c3415ff46569330de2d0820b55a31859f2c7efde1df96ce5bb59c731a872d51
}
This hash matches the value produced by the TypeScript reference implementation and the Python conformance implementation for the same input.

​
How the hash is computed

The Rust implementation follows the same three-step pipeline as the TypeScript reference:
1

Normalize the envelope

Extract only the hash-scoped fields: type, domain, sources, artifactHash, tier, payload, and derivation. Sort sources deterministically when there is more than one entry. Fall back to parents if sources is absent.
2

Canonicalize

Serialize the normalized object using JCS (RFC 8785): object keys sorted lexicographically, no whitespace, null values rejected.
3

Hash with domain prefix

Compute keccak256(b"KB_V1" + canonical_utf8) using the sha3 crate. Return the result as a 0x-prefixed lowercase hex string.

​
Canonical test vectors

The test suite covers the same vectors as the Python and TypeScript implementations:
Vector groupCoverage
types/*All canonical KB types: practice, pattern, prompt, synthesis, adaptation, compliance, enhancement, state-machine
edge-cases/*Empty payload fields, large payloads, max sources, unicode content
derivation/single-parentSingle-parent lineage hash stability
derivation/multi-parentMulti-parent source sorting
derivation/parent-sortSorted and unsorted sources must produce identical kbHash
Each vector directory contains envelope.json (input) and expected.json (expected kbHash).