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.

A Knowledge Block (KB) is the fundamental unit of ALX Protocol. Every artifact you publish, reference, or derive is a KB: an immutable, typed object whose identity is derived entirely from its content. Because identity is content-addressed, two KBs with identical content and lineage always produce the same identifier (kbHash), regardless of who created them or when. This makes KBs safe to share, cache, and verify across independent systems.

​
What a Knowledge Block contains

Every KB is made up of four properties:
  • Content — the type-specific payload, serialized in a canonical form that guarantees byte-identical output for identical input.
  • Identity — kbHash, a deterministic content address derived by hashing the canonical envelope under the KB_V1 domain tag. See Identity.
  • Dependencies — the sources array, which lists the kbHash values of every parent KB this one builds on. See Lineage.
  • Provenance — domain, tier, and artifactHash, which record where the artifact belongs, who can access it, and a cryptographic commitment to the off-chain artifact bytes.

​
The canonical envelope

When you publish a KB, the protocol serializes it into a canonical envelope — the object that becomes the hash preimage. The envelope shape looks like this: 
{
  "type": "practice",
  "domain": "software.security",
  "sources": [
    "0x3a1b...c4f2",
    "0xd7e8...91ab"
  ],
  "artifactHash": "0xf3c9...7d11",
  "tier": "open",
  "payload": {
    "type": "practice",
    "rationale": "Rotate signing keys to limit exposure window.",
    "contexts": [],
    "failureModes": []
  },
  "derivation": {
    "type": "compose",
    "inputs": [
      { "kbId": "0x3a1b...c4f2", "selectors": ["payload.rationale"] }
    ],
    "recipe": { "strategy": "merge" }
  }
}
Only the fields listed in the envelope participate in identity hashing. Fields like curator, createdAt, signature, and transport metadata are excluded from the hash preimage — changing them does not change the KB’s identity.
The derivation field is optional. It is only present when the KB was constructed from other KBs using a deterministic synthesis method (compose, transform, extract, or summarize).

​
Hash-scoped fields

FieldTypeRole
typestringKB type (e.g. "practice")
domainstringDomain classifier (e.g. "software.security")
sourcesstring[]Parent kbHash values; sorted and deduplicated before hashing
artifactHashstringCryptographic commitment to the off-chain artifact bytes
tierstringAccess tier: open, verified, premium, or restricted
payloadobjectType-specific content
derivationobjectDerivation recipe, when present

​
Excluded fields

The following are never included in the hash preimage:
  • kbHash itself (the top-level embedded field is stripped before hashing)
  • curator and createdAt
  • signature
  • Transport or indexing metadata

​
KB types

ALX Protocol defines a registry of KB types. Each type corresponds to a specific payload schema. The six foundational types are:
TypeSerialized valueDescription
Practice"practice"A recommended approach with rationale, contexts, and failure modes
Feature"feature"An interface contract with test scaffold
StateMachine"stateMachine"States, transitions, and invariants
PromptEngineering"promptEngineering"A prompt template with model version and evaluation criteria
ComplianceChecklist"complianceChecklist"Jurisdiction-tagged requirements with evidence mappings
Rubric"rubric"Scoring dimensions, logic, and pass/escalate thresholds
Type values in the canonical envelope and payload use camelCase (e.g. "stateMachine", not "StateMachine"). Using the wrong casing will produce a different kbHash.
The protocol also supports extended types including synthesis, pattern, adaptation, enhancement, factual, derived, procedure, toolDefinition, codebank, researchArtifact, knowledgeGraph, agentMemory, evaluation, capability, agentIdentity, demandBeacon, hypothesis, inquiry, beliefUpdate, reasoningChain, collaboration, knowledgeGap, agentManifest, and protocolEndorsement.

​
KB lifecycle

A Knowledge Block moves through the following stages from creation to verification:
  1. Creation — You construct the envelope with type, domain, sources, tier, payload, and optionally derivation. The artifactHash is computed from the artifact bytes.
  2. Canonicalization — The protocol serializes the hash-scoped fields using RFC 8785–style JSON Canonicalization Scheme (JCS): keys sorted alphabetically, no extra whitespace, no undefined or null values.
  3. Identity derivation — kbHash is computed as keccak256(UTF8("KB_V1") + canonical_string). This is the stable, verifiable identifier for the KB.
  4. Publication — The kbHash is committed to the registry contract. The artifact content is stored at a durable location referenced by artifactHash or cidV1.
  5. Verification — Any party can recompute kbHash from the canonical envelope and confirm it matches the published value. They can also retrieve the artifact bytes and verify them against artifactHash.
Because publication commits both kbHash and artifactHash to the registry, you can independently verify the KB’s identity and the integrity of its artifact bytes — even when they come from different sources.

​
Immutability

Once a KB is published, it cannot be changed. Its kbHash, sources, and payload are fixed. If you need to update content or change lineage, you publish a new KB — optionally referencing the old one in its sources array to preserve history. This append-only model means the full derivation history of any KB is always traceable. For more on how lineage works, see Lineage. For the full identity derivation formula, see Identity.