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.

ALX Protocol is not only a type contract — it is also a trust boundary. The protocol minimizes reliance on trusted intermediaries by making identity verification cryptographic and validation rules explicit and deterministic. This page covers the trust model, replay protection mechanisms, content integrity expectations, and the boundaries of what the protocol does and does not protect against. For responsible disclosure, contact security@xandrlabs.ai.

​
Trust model

ALX Protocol v1 operates under the following trust assumptions:
  • Clients trust the server to emit protocol-conformant envelopes. A client must not assume that a response is valid simply because it arrived — it must validate only documented canonical fields.
  • Identity verification is cryptographic, not authority-based. Signatures are verified against public keys; kbHash is derived deterministically from envelope content.
  • Capability negotiation is informational only. Advertised capabilities are not proof of authorization.
  • A protocol-visible proof or receipt is independently verifiable against canonical protocol state. If the protocol presents something as verifiable, you can verify it without trusting the server’s word.
Clients must not treat undocumented fields as stable protocol contract, and must not assume that implementation-specific behavior beyond documented guarantees will remain consistent.

​
EIP-712 signed requests

ALX Protocol uses EIP-712 typed-data signing for authenticated requests. The @alx/protocol/core subpath provides the signing and verification surface: 
import { core } from "@alx/protocol";

const {
  buildProtocolSigningDomain,
  verifySignedProtocolRequest,
  NonceTracker,
  SIGNED_PROTOCOL_REQUEST_TYPES,
} = core.signedRequest;
A signed request carries six fields that are included in the EIP-712 hash:
FieldTypePurpose
kbIdbytes32The Knowledge Block being queried.
querystringThe query string.
agentaddressThe Ethereum address of the signing agent.
nonceuint256Monotonically increasing per-agent value to prevent replay.
expiryuint64Unix timestamp after which the request is invalid.
chainIduint256Target chain identifier to prevent cross-chain replay.
buildProtocolSigningDomain defaults verifyingContract to the zero address (0x000...000). This is safe only for off-chain verification. Any on-chain verifier must supply its deployed contract address. Using the zero address on-chain allows a signature produced in one context to be replayed against any other contract that also accepts the zero-address domain. Production deployments must pass verifyingContract explicitly.

​
Replay protection

ALX Protocol defines replay protection at the request level using two mechanisms: Nonce tracking. The NonceTracker class tracks consumed nonces per agent address. Once a nonce is consumed, the same nonce cannot be reused by the same agent. Servers operating in production should use a NonceTracker (or an equivalent persistent store) when calling verifySignedProtocolRequest. Expiry fields. All signed payloads must include an expiry field. A request whose expiry timestamp has passed is rejected. Short expiry windows limit the blast radius if a signed request is intercepted. 
const tracker = new NonceTracker();

const result = verifySignedProtocolRequest({
  domain: buildProtocolSigningDomain({ chainId: 8453n }),
  request: { kbId, query, agent, nonce: 42n, expiry: BigInt(Math.floor(Date.now() / 1000) + 300), chainId: 8453n },
  signature,
  now: BigInt(Math.floor(Date.now() / 1000)),
  nonceTracker: tracker,
});
A SignedRequestValidationError is thrown with one of the following codes on failure: MALFORMED_REQUEST, INVALID_SIGNATURE, SIGNER_MISMATCH, EXPIRED_REQUEST, CHAIN_MISMATCH, or NONCE_REUSED.

​
artifactHash validation

Every published Knowledge Block binds its artifact bytes to the envelope via artifactHash. When you retrieve artifact content by CID or other address, always validate the retrieved bytes against the published artifactHash before using the content. 
import { artifactHashFromBytes } from "@alx/protocol";

async function fetchAndValidate(cid: string, expectedArtifactHash: string): Promise<Uint8Array> {
  const bytes = await fetchFromIPFS(cid);
  const computed = artifactHashFromBytes(bytes);
  if (computed !== expectedArtifactHash) {
    throw new Error(`artifactHash mismatch: expected ${expectedArtifactHash}, got ${computed}`);
  }
  return bytes;
}
A CID without an active IPFS pin should be treated as at-risk. Do not assume durability from the presence of a CID alone. A durable publication requires a verified IPFS pin, a verified Arweave transaction, or an equivalent content-addressable archive with a defined retention policy. KB identity (kbHash) remains valid even if the artifact is unretrievable — identity and retrievability are independent.

​
Threat model

​
What the protocol protects against

  • Signature forgery. EIP-712 signatures bind the request to the signer’s private key. Forging a valid signature without the key is computationally infeasible.
  • Request replay within the nonce window. NonceTracker and per-agent nonce tracking prevent reuse of a consumed nonce.
  • Expired request replay. Requests with a passed expiry are rejected before signature verification.
  • Cross-chain replay. The chainId field in the EIP-712 domain and request payload prevents a signature valid on one chain from being accepted on another.
  • Content tampering. kbHash is a cryptographic commitment to the canonical envelope. Any change to a hash-scoped field produces a different hash, breaking the binding.
  • Artifact substitution. artifactHash binds the artifact bytes to the envelope. Substituting different bytes for a CID produces a different hash, detectable by validation.

​
What the protocol does not protect against

  • Compromised signer keys. ALX Protocol v1 does not define an on-chain revocation mechanism. All signatures produced by a compromised key remain cryptographically valid at the protocol level. Mitigations include short expiry windows, application-layer blocklists, and the emergency pause on AlexandrianRegistryV2.
  • KB retraction. Published Knowledge Blocks are immutable by protocol design. There is no protocol-level mechanism to retract a published KB. A KB may be superseded by a newer KB that declares the old kbHash in its lineage.
  • Full replay-resistant economic operations. Replay resistance for credit-consuming routes (execute, recommend, billing webhooks) is tracked as active protocol-hardening work, not a proven guarantee.
  • Downgrade abuse beyond documented rules. Fuzz and matrix tests for capability downgrade safety are pending.

​
Current security status

The following areas are implemented and have executable proof:
  • Replay and expiry validation
  • Malformed-signature rejection
  • Tampered signed-payload rejection
  • Signer and actor mismatch rejection
  • Artifact-receipt verification against expected kbHash and artifactHash
The following areas are active hardening work:
  • Replay-resistant economic operations (double-submit prevention on credit-consuming routes)
  • Broader receipt verification for non-happy-path and tampered payloads
  • Downgrade/capability abuse resistance
Treat unproven areas as normative targets rather than verified runtime guarantees.