Decentralized Storage Assets (IPFS & Arweave)

Art Blocks Engine Flex supports several types of external dependencies — including PostParams (on-chain), multiple Dependency Registry entries, and decentralized storage networks. This page covers the decentralized storage path: what a CID is, how preferred gateway URLs are constructed, how to upload assets to IPFS or Arweave, and how to reference them in your generative script.

When to Use Decentralized Storage

Engine Flex supports many use cases beyond decentralized storage — see What is Art Blocks Engine? for the full picture. This page focuses specifically on the IPFS and Arweave storage path, which is useful when your project incorporates assets too large to store efficiently on-chain:

• Images — base images for generative manipulation (1-of-1-of-X outputs)
• Audio — generative audio composed from uploaded samples
• ML models — machine learning models (e.g. TensorFlow.js models)
• Large data sets — any structured data used as generative input

Your generative script still lives fully on-chain. External assets are referenced by CID (content identifier) and loaded at render time via the preferred gateway.

CIDs and Gateways in Practice

A CID is just an identifier for a piece of content on a decentralized network — it doesn't include a protocol, domain, or path. To actually fetch the content over HTTP, you need to combine it with a gateway URL: a web server that knows how to translate a CID into the underlying content.

finalURL = gatewayURL + CID

That's the entire mental model. Everything else on this page is detail around getting the CID and gateway values right.

IPFS CIDs

IPFS CIDs come in two formats, and you may encounter either depending on which tool generated it:

Both formats work identically as far as Art Blocks and IPFS gateways are concerned — use whichever your upload tool gives you, and paste it verbatim into the CID field in the Creator Dashboard.

Arweave CIDs (Transaction IDs)

Arweave doesn't use the term "CID," but the Art Blocks Creator Dashboard uses the same CID field for Arweave dependencies. For Arweave, the value you enter is the transaction ID returned after your upload completes:

DKm4z1RwyMnhSs9dHkQPqUw4wXAqjEuNsCr1ScYoOZM

Arweave transaction IDs are always 43 characters, base64url-encoded (letters, numbers, -, and _).

Preferred Gateway URLs

A gateway URL is the prefix that, when concatenated with a CID, produces a working link to the content. Every gateway has its own URL shape — the important thing is that the gateway value stored on your contract already includes any trailing slash or path segment needed, so that simple string concatenation with the CID produces a valid URL.

The preferred gateways are configured at the contract level by the Engine admin — not per-project or per-asset. Every project on a given Engine Flex contract shares the same preferred IPFS and Arweave gateways. If you're an artist and need a gateway changed, contact your Engine partner or the Art Blocks team; if you're an Engine partner, see the Engine Partner FAQ for how to request a change.

Accessing Flex Assets in Your Script

External assets are injected into tokenData.externalAssetDependencies, alongside tokenData.preferredIPFSGateway and tokenData.preferredArweaveGateway. Access them like this:

const dep = tokenData.externalAssetDependencies[0]; // first external dependency

if (dep.dependency_type === "IPFS") {
  const url = tokenData.preferredIPFSGateway + dep.cid;
  // fetch or load the asset from `url`
} else if (dep.dependency_type === "ARWEAVE") {
  const url = tokenData.preferredArweaveGateway + dep.cid;
  // fetch or load the asset from `url`
} else if (dep.dependency_type === "ONCHAIN") {
  const data = dep.data; // already resolved on-chain data string
}

For projects with multiple external assets:

const assets = tokenData.externalAssetDependencies;
// e.g. assets[0] is the base image, assets[1] is an audio sample

Concrete End-to-End Example

Here's a full walkthrough of a project with one IPFS image dependency, from Creator Dashboard configuration to a resolved fetch in the browser.

1. You configure a Flex Asset in the Creator Dashboard:

2. Your Engine Flex contract has a preferred IPFS gateway configured at the contract level:

https://ipfs.artblocks.io/ipfs/

3. At render time, the Generator injects the following into tokenData:

let tokenData = {
  hash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  tokenId: "42000001",
  preferredIPFSGateway: "https://ipfs.artblocks.io/ipfs/",
  preferredArweaveGateway: "https://arweave.net/",
  externalAssetDependencies: [
    {
      dependency_type: "IPFS",
      cid: "QmbxU6subfSzzpxketBhVBVCGhFBPdTSB8nCtppGZtpZGf",
      data: null,
    },
  ],
};

4. Your script constructs the final URL and loads the asset:

const dep = tokenData.externalAssetDependencies[0];
const imageUrl = tokenData.preferredIPFSGateway + dep.cid;
// imageUrl === "https://ipfs.artblocks.io/ipfs/QmbxU6subfSzzpxketBhVBVCGhFBPdTSB8nCtppGZtpZGf"

let baseImg;
function preload() {
  baseImg = loadImage(imageUrl);
}

The same pattern applies to an Arweave dependency — swap dependency_type: "ARWEAVE", use dep.cid as the transaction ID, and read from tokenData.preferredArweaveGateway instead.

Uploading Your Assets

You'll need to pin your file to IPFS or upload it to Arweave before you have a CID to configure. A few popular options:

• Pinata — IPFS pinning with a simple upload UI. Free plan covers up to 100 files / 1 GB. After upload, the file's CID is shown in your Files list.
• Filebase — IPFS pinning with 3x geo-redundant nodes. Free tier covers up to 5 GB / 1,000 files.
• Ardrive or Irys — for permanent, pay-once storage on Arweave. After upload, you'll receive a transaction ID to use as your CID.

Each service's dashboard shows the resulting CID (or transaction ID) directly after upload — copy it into the Creator Dashboard as described below. For production projects, consider a dedicated/custom gateway (offered by Pinata and Filebase) rather than the shared public gateway, which is best suited for testing.

Configuring Flex Assets in the Creator Dashboard

Once you have your CIDs, configure your external asset dependencies in the Art Blocks Creator Dashboard:

1. Navigate to your project → Scripts
2. In the Flex Assets section, add your dependencies
3. For each dependency, specify a Dependency Type (IPFS, ARWEAVE, or ONCHAIN) and its CID
4. The order of dependencies corresponds to indices in tokenData.externalAssetDependencies

Larger assets take longer to load at render time, so test with realistic network conditions to ensure assets load within your render delay window.

For Engine Partners

The examples above cover the artist/script side of IPFS and Arweave assets. If you're an Engine partner responsible for configuring or updating the preferred gateway at the contract level, see the Engine Partner FAQ and What is Art Blocks Engine? for the partner-facing side of this feature.