Skip to main content

Conformance Vectors

Conformance vectors provide fixed inputs and expected outputs for the protocol rules that must stay deterministic. A passing implementation reproduces the published bytes, hashes, Graph results, and verification outcomes.

Vector Format​

Each suite file lists vectors with an id, a description, an input, and an expected result. An accepted input expects an output value, and a rejected input expects an error identifier. Vectors in suites that test more than one operation also name an operation. The test vector schema and expected results schema define the complete format.

Accepted input (C8)
{
  "id": "C8",
  "description": "nested object with sorted keys",
  "input": {"b": {"d": 1, "c": 2}, "a": 3},
  "expected": "{\"a\":3,\"b\":{\"c\":2,\"d\":1}}"
}
Rejected input (CN4)
{
  "id": "CN4",
  "description": "integer above MAX_SAFE_INTEGER MUST be rejected",
  "input": 9007199254740992,
  "expected": {"errorCode": "ALX_CANONICALIZATION_UNSAFE_INTEGER"}
}

Use the Vector Groups​

The required-suite manifest records each suite's path, operation, vector count, and SHA-256 digest. Compare the digests to confirm that an implementation runs the published vectors. Run the 15 required core suites, canonicalization and identity first, then Graph and Trace. Run an extension's suites only when the implementation claims that extension.

Seven core suites cover canonical bytes, rejected values, raw JSON ingress, Block identity, and parent normalization.

Suite fileVectorsCoverage
test-vectors/canonicalization/canonicalization.json31Canonical bytes for accepted values
test-vectors/canonicalization/canonicalization-negative.json11Rejected values
test-vectors/canonicalization/canonicalization-depth.json2Depth 128 accepted, depth 129 rejected
test-vectors/ingress/raw-json.json6Raw JSON ingress
test-vectors/identity/block-identity.json8contentHash and blockHash derivation
test-vectors/blocks/parent-normalization.json10Parent normalization
test-vectors/blocks/parent-limits.json2The 256-parent limit

When to Rerun the Vectors​

Rerun the core suites after any change to serialization, hashing, parent normalization, Graph verification, or Trace code, and an extension's suites after changing that extension. Run Conformance Tests lists every rerun trigger and the commands.