Skip to main content

Integrate ALX

A minimal integration selects application content, creates an ALX Block, stores the complete Block, and verifies the Block at every trust boundary. The workflow adds deterministic identity and declared lineage to existing application data.

Creating, storing, and verifying Blocks requires no ALX account or API key. ALX does not require a specific database, transport, authentication system, blockchain, or hosted service.

Integration Model​

  1. Select application content.
  2. Create an ALX Block.
  3. Store the complete Block.
  4. Verify the Block at every trust boundary.
  5. Build context from connected Blocks when the workflow requires prior work.

validateBlock() proves that a Block is internally consistent, not that the Block is the one the application expected. A different Block with valid hashes also passes validateBlock(); comparing blockHash with the identity the application stored, received through a trusted channel, or committed rejects the substitution. The script below follows steps 1 to 4:

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

// Steps 1 and 2: select durable content and create a Block.
const block = createBlock({invoiceId: 'INV-1042', total: 1250, currency: 'EUR'}, []);

// Step 3: store the complete Block next to the application record.
const stored = JSON.stringify(block);
const expectedHash = block.blockHash;

// Step 4: at the next trust boundary, parse strictly, validate, and compare.
const received = parseStrictJson(stored);
if (!validateBlock(received).ok || received.blockHash !== expectedHash) {
  throw new Error('Block rejected');
}

Select Content​

Select only JSON-serializable application content that represents the data object. Exclude timestamps, request metadata, temporary values, and other fields that change independently unless those values form intentional, durable content.

contentHash depends on the selected content. blockHash depends on the selected content and normalized parentHashes. A root Block has an empty parentHashes array; a derived Block declares only its direct parents.

Store the Block​

Store all five Block fields with the related application data. ALX does not define a storage engine, record layout, transport, or retention policy.

An application may distribute the serialized Block through IPFS or another content-addressed system. A CID identifies retrieved bytes; blockHash identifies the ALX Block.

Verify at Trust Boundaries​

Parse retrieved bytes with parseStrictJsonBytes() or text with parseStrictJson(); both reject duplicate JSON members. Run validateBlock(), then compare the recomputed blockHash with the expected identity. Validate Blocks covers results and errors.

Block validation does not confirm content truth, author identity, authorization, or parent availability. When complete lineage is required, load every referenced parent Block, validate each one, and run Graph verification. Missing parents produce incomplete, not verified ancestry. Compose Blocks into a Graph shows the call.

Build Context from Connected Blocks​

When a workflow needs prior work as context, verify the Graph, trace declared ancestry, and select content as shown in Build Context from Blocks. ALX supplies deterministic identities and declared relationships; the application controls retrieval, relevance, ordering, context limits, and interpretation.

Add an Optional Commitment​

Blockchain commitments remain optional. Block creation, storage, Block validation, and Graph verification do not require blockchain infrastructure.

  • Commit one blockHash when recording a single Block.
  • Build a Merkle tree and commit the Merkle root hash when recording a set of Block hashes.
  • Retain a Merkle proof when later inclusion verification is required.

When to Use Each Layer​

Apply only the layers required by the application trust boundary.

RequirementLayer
Verify stored content and declared parentsBlock validation
Verify direct parents and complete lineageGraph verification
Verify inclusion in a committed setMerkle proof verification
Record a hash onchainBlockchain commitment