Skip to main content

Conformance Tests

Conformance tests check that an ALX implementation produces the expected protocol-defined results for the canonical test vectors. Shared vectors let independent implementations find behavioral differences before they exchange or verify Blocks across implementation boundaries.

Why Conformance Testing Matters​

Two implementations can accept the same JSON input and still produce different canonical bytes, normalized parent sets, or hashes. Differences in number formatting, string escaping, Unicode handling, key ordering, parent normalization, or hash function choice produce incompatible Block identities. Conformance defines what core and extension conformance require, and Conformance Vectors lists every suite.

Run the Maintained Implementations​

From the ALX Protocol source repository, pnpm run test:conformance builds the TypeScript SDK and runs it against the 15 required core suites in protocol/suites.json. pnpm run verify:cross-language also runs the Python and Rust implementations and compares all three; it requires Python 3.11 or later and a Rust toolchain. pnpm run test:extension runs the optional Merkle and signing extension suites. Run the core suites:

pnpm run test:conformance

Test Another Implementation​

The runner tests any implementation that runs as a process, reads one JSON operation per line on standard input, and writes one JSON result per line on standard output. A failed operation returns {"error": "..."} with the error identifier in brackets, for example {"error": "[ALX_INVALID_HASH] invalid hash: 0x1234"}. The runner compares that identifier with the vector's expected error.

The JSON transport cannot carry language-native values such as negative zero, undefined, NaN, BigInt, Symbol, or cyclic references. The runner reports those cases as skipped, and a full conformance claim also requires the implementation's own tests for them. conformance/README.md in the repository lists every operation with its input and output. The commands below send one operation and run every core suite:

Send one operation
echo '{"operation":"canonicalize","input":{"b":2,"a":1}}' | ./my-impl
Response
{"output":"{\"a\":1,\"b\":2}"}
Run every core suite
node conformance/bin/run.js --impl "./my-impl"

When to Run Conformance Tests​

Run the conformance tests in continuous integration for any implementation that creates or verifies ALX Blocks, and also when:

  • Implementing ALX in another language or runtime
  • Changing canonicalization, parent normalization, or hash derivation
  • Updating Block validation, Graph verification, or Attribution Trace computation
  • Changing a claimed signing or Merkle extension
  • Upgrading serialization or cryptographic dependencies
  • Preparing an implementation for release

Explore​