Skip to main content

Validate Blocks

Block validation recomputes contentHash and blockHash, compares both values with the stored identities, and reports whether the complete Block record is internally consistent.

Validate at Boundaries​

Stored or transported content can change independently from recorded identities. Recomputing both hashes before processing a Block detects mismatched content, lineage, or stored identity fields without interpreting the payload.

Parse received Block JSON with parseStrictJson(), not JSON.parse(). JSON.parse() keeps the last of two duplicate object members, so two systems can read different content from the same bytes. parseStrictJson() rejects duplicate members and trailing data, and parseStrictJsonBytes() also rejects invalid UTF-8.

Validate the Block​

acceptBlock() returns the Block when the supplied content and parent set reproduce both stored identities, and null otherwise. The Failure Cases table on Create and Validate a Block shows the result of each kind of change.

When ok is false, inspect each match value and compare the stored and recomputed hashes. If both match values are true, check parentsCanonical (stored parentHashes must be lowercase, deduplicated, and sorted) and selfRef.

import {parseStrictJson, validateBlock} from '@alx-protocol/sdk';

export function acceptBlock(text) {
  try {
    const block = parseStrictJson(text);
    const result = validateBlock(block);
    if (result.ok) return block;
    console.error({
      blockHash: result.blockHash,
      contentHash: result.contentHash,
      parentsCanonical: result.parentsCanonical,
      selfRef: result.selfRef,
    });
  } catch (error) {
    console.error(error.message);
  }
  return null;
}

Errors​

validateBlock() throws ALX_SCHEMA_INVALID for a record that is not exactly the five Block fields, ALX_UNSUPPORTED_VERSION for a protocolVersion other than "1", and ALX_INVALID_HASH for a malformed hash. Each message starts with the identifier in brackets, for example [ALX_SCHEMA_INVALID] Block fields do not match the core Block schema, and the ErrorCode export lists every identifier. parseStrictJson() throws a SyntaxError for malformed JSON, duplicate members, or trailing data. Treat any thrown error as a rejected Block.

Graph Verification​

Block validation does not check parents. For a non-root Block, run Graph verification separately: a valid status confirms that every required parent was available and every examined relationship satisfies the protocol rules, and a missing parent returns incomplete. Compose Blocks into a Graph shows the call.

When to Validate​

Validate a Block after loading the Block from storage, receiving the Block from another system, or before using the Block as a Graph or commitment input.