IPFS Blockchain Publisher Extension

The IPFS Blockchain Publisher Extension is an optional extension of the Cardano L1 Blockchain Publisher. It is used to publish larger transaction metadata to IPFS and only store the resulting IPFS CID on the Cardano blockchain. This keeps the on-chain transaction small, while the complete metadata can still be retrieved and verified through IPFS.

Overview

Without the IPFS extension, the Cardano L1 Publisher serialises the complete transaction metadata into the Cardano transaction. This is simple, but it is limited by the maximum transaction size.

When the IPFS extension is enabled, the publisher follows a different flow:

1. The transaction metadata is created in the same API1 format as the normal Cardano L1 publishing flow.
2. The metadata is validated against the transaction metadata schema.
3. The data object is removed from the on-chain metadata and published to IPFS.
4. The returned IPFS CID is added to the on-chain metadata as ipfs.
5. The Cardano transaction is built, signed, and submitted with the reduced metadata.

The on-chain metadata therefore contains the reference to the IPFS document instead of the full transaction data. The referenced IPFS document contains the original data object.

Supported IPFS Publishers

The extension provides two IPFS publisher implementations.

Local IPFS Node

The local IPFS node publisher connects to an IPFS node through the IPFS HTTP API. It is useful for development, self-hosted environments, and deployments where the IPFS infrastructure is operated by the same organisation.

Blockfrost IPFS

The Blockfrost IPFS publisher uploads the metadata through the Blockfrost IPFS API. It is useful when the deployment already uses Blockfrost as managed infrastructure and does not operate its own IPFS node.

Only one IPFS publisher should be enabled for a deployment. If no IPFS publisher is enabled, the Cardano L1 Publisher uses the normal on-chain metadata flow.

Configuration

The extension is activated by enabling one of the IPFS publisher implementations.

Local IPFS Node Configuration

• lob.blockchain_publisher.ipfs.local.enabled: Enables the local IPFS node publisher when set to true.
• lob.blockchain_publisher.ipfs.local.node: The IPFS node address in the format host:port. If no port is provided, port 5001 is used.

Example:

lob.blockchain_publisher.ipfs.local.enabled=true
lob.blockchain_publisher.ipfs.local.node=127.0.0.1:5001

Blockfrost IPFS Configuration

• lob.blockchain_publisher.ipfs.blockfrost.enabled: Enables the Blockfrost IPFS publisher when set to true.
• lob.blockchain_publisher.ipfs.blockfrost.url: The Blockfrost IPFS upload endpoint.
• lob.blockchain_publisher.ipfs.blockfrost.project_id: The Blockfrost project id used for authentication.

Example:

lob.blockchain_publisher.ipfs.blockfrost.enabled=true
lob.blockchain_publisher.ipfs.blockfrost.url=https://ipfs.blockfrost.io/api/v0/ipfs/add
lob.blockchain_publisher.ipfs.blockfrost.project_id=<project-id>

Publishing Process

The IPFS publishing process is part of the Cardano L1 transaction creation. The Accounting Core module still emits the same TransactionLedgerUpdateCommand, and the Blockchain Publisher still emits the same ledger update events. The extension only changes how the transaction metadata is stored.

If publishing to IPFS fails, the blockchain transaction is not created. The failure is returned as a publishing error, because the on-chain metadata would otherwise point to missing off-chain data.

Data Availability

The Cardano blockchain stores the IPFS CID in the transaction metadata. The full transaction metadata is available from IPFS through that CID.

Deployments that use this extension should ensure that the IPFS content remains available for audit and verification. For self-hosted IPFS this means pinning and operating the node reliably. For Blockfrost IPFS this means using the Blockfrost IPFS service according to the deployment requirements.