Skip to main content

IPFS

IPFS distributes serialized ALX Blocks through content-addressed retrieval.

Applications receive a CID, retrieve the associated bytes, and validate the resulting Block locally. ALX blockHash identifies canonicalized Block content and declared parents. An IPFS CID identifies raw file bytes. Applications retain both identifiers when distributing Blocks through IPFS.

Two Identifiers​

Applications maintain the mapping between blockHash and CID.

PropertyALX blockHashIPFS CID
RoleIdentifies an ALX BlockIdentifies retrievable bytes
Hash functionKeccak-256Multihash selected by the CID
InputCanonicalized content and parentHashesRaw file bytes
Verified byA conforming ALX implementationIPFS content addressing

Application Integration​

Applications select and operate the IPFS client, gateway, pinning policy, and identifier mapping. Treat retrieval transport and gateway responses as untrusted input until local validation succeeds. After retrieval:

  1. Parse the retrieved bytes with parseStrictJsonBytes() from @alx-protocol/sdk to reject invalid UTF-8 and duplicate JSON members.
  2. Call validateBlock() and require ok to be true.
  3. Compare blockHash.recomputed with the expected blockHash.
  4. Accept the Block only after both checks succeed.

When to Use IPFS​

Use IPFS when an application needs CID-based distribution across infrastructure boundaries. Use application storage when the application controls persistence and retrieval directly. The selected storage layer preserves ALX Block identity and declared lineage.

Responsibilities Around IPFS​

  • Availability: Configure nodes or pinning services for the required retention period.
  • Lineage: Read declared parent relationships from parentHashes inside each Block.
  • Block identity: Verify blockHash with ALX protocol rules after retrieving the bytes.
  • Identifier mapping: Retain the CID-to-blockHash association in the application.