Skip to main content

Distribute, Commit, and Verify a Block

Create and validate a Block first. Add IPFS distribution or blockchain commitment evidence when the application requires distribution or public commitment records.

Neither optional layer changes the Block identity or declared lineage. The supported Base deployment, ALXAnchor, is listed on the ALX on Base page.

1. Create and Validate Locally​

Install the package as shown in Quick Start. Create prepare-block.mjs in the project and run the script. Keep the printed blockHash. The Block retains the same ALX identity whether stored locally or distributed elsewhere.

prepare-block.mjs
import {writeFile} from 'node:fs/promises';
import {createBlock, validateBlock} from '@alx-protocol/sdk';

const block = createBlock(
  {type: 'research-note', text: 'A reproducible ALX example'},
  [],
);
const result = validateBlock(block);

if (!result.ok) throw new Error('Block validation failed');

await writeFile('research.block.json', `${JSON.stringify(block, null, 2)}\n`);
console.log(block.blockHash);
Terminal
node prepare-block.mjs

2. Optionally Distribute Through IPFS​

The @alx-protocol/sdk package does not provide an IPFS publishing client, gateway resolver, Kubo adapter, or CID mapping store. An application that chooses IPFS must use an application-controlled IPFS client to publish research.block.json, retain the resulting CID with the expected blockHash, and arrange pinning when availability matters.

When the application retrieves bytes from a gateway or node, parse the bytes strictly, validate the Block locally, and compare its blockHash with the expected identity. parseStrictJsonBytes() decodes UTF-8 without replacement and rejects duplicate JSON members. A different Block with valid hashes also passes validateBlock(); the comparison with the expected blockHash rejects it. The CID identifies raw file bytes for retrieval; the blockHash identifies the ALX Block. Availability still depends on a node or pinning service keeping the content available. Create verify-retrieved.mjs and run the script with the blockHash kept from step 1:

verify-retrieved.mjs
import {readFile} from 'node:fs/promises';
import {parseStrictJsonBytes, validateBlock} from '@alx-protocol/sdk';

const expectedHash = process.argv[2]; // the blockHash printed by prepare-block.mjs
const retrievedBlock = parseStrictJsonBytes(await readFile('retrieved.block.json'));
const result = validateBlock(retrievedBlock);

if (!result.ok || retrievedBlock.blockHash !== expectedHash) {
  throw new Error('Retrieved Block rejected');
}
console.log('accepted', retrievedBlock.blockHash);
Terminal
node verify-retrieved.mjs 0x…

3. Optionally Commit Evidence​

Commit a public record of a deterministic value when the application requires one. ALXAnchor records commitments on Base (chain ID 8453) at 0xF6E12e7052F15c44AE926E50A0a68FAB5E35ea46 in two forms:

  • anchor(bytes32) records one value: a single blockHash, or a Merkle root hash that represents many Block hashes. A Merkle root hash requires the application to retain inclusion proofs.
  • anchorBatch(bytes32 batchId, bytes32[] blockHashes) records 2 to 256 Block hashes individually and skips values already recorded.

isAnchored() reports whether a value is recorded, anchoredAt() returns the block timestamp of the first record, and anchoredBy() returns the address that submitted the first record. ALXAnchor accepts submissions from any address, so anchoredBy() identifies the first submitter, not the Block's author. Before integrating, confirm the address, verified source, and ABI on the ALX on Base page; ABI lists every entry. Trust Boundary lists the claims a commitment does not establish.

4. Verify the Right Claim​

For an offchain Merkle example, follow Verify Commitment Inclusion. For deployment readiness, see Deployment Requirements.

QuestionVerify withWhat a successful result establishes
Is the supplied Block internally consistent?validateBlock()The recorded identities match the Block content and declared parents.
Did retrieved bytes match the expected Block?parseStrictJsonBytes(), validateBlock(), and a blockHash comparisonThe retrieved Block is internally consistent and has the expected identity.
Is a Block hash in a committed set?A Merkle inclusion proofThe hash is included in the set represented by the supplied Merkle root hash.
Was the supplied blockHash or Merkle root hash recorded onchain?isAnchored(), anchoredAt(), and anchoredBy() on ALXAnchor (Base, chain ID 8453)The value was recorded, with the block timestamp and submitting address of the first record.

When to Use This Workflow​

Use the distribution and commitment workflow when an application needs to share serialized Block data outside application-controlled storage, preserve commitment evidence for a Block hash, or evaluate Block, retrieval, inclusion, and onchain record claims. Validate each Block locally before evaluating distribution or commitment evidence.