Storage: IPFS, pins and copies

The blockchain holds the record of every article, but not its text. The text and its figures live on IPFS, and the blockchain keeps their fingerprint. This page explains how that works, who keeps copies, and how you can keep one yourself. For the steps of publishing, see Publish an article.

IPFS and CIDs in plain words

IPFS is a network where a file is found by its fingerprint instead of its location. You do not ask “give me the file at this address”; you ask “give me the file whose fingerprint is this”, and any computer that has it can answer.

That fingerprint is the CID (content identifier). It is computed from the content itself, so:

• the same content always gives the same CID, wherever it is stored;
• any change, even one character, gives a different CID;
• whoever receives the content can compute the CID again and check that nothing was altered.

Pinning means asking an IPFS computer (a node) to keep a file permanently. A file stays available on IPFS as long as at least one node that can be reached keeps it pinned. Nobody “owns” a CID: anyone may pin it, and extra pins are always safe, because the CID guarantees they all hold the same content.

What is stored

Content	Form on IPFS	CID starts with
an article version	a folder: index.md (the text) and an optional assets/ folder (figures, data), at most 20 MB	bafybei...
a review or a comment	one Markdown file, at most 256 KiB, without images	bafkrei...

Each new version of an article is a new folder with a new CID; the old one stays readable. What a folder may contain is detailed in Write the article.

The canonical CID

Different tools can produce different CIDs for the same files, depending on how they cut and arrange them. So that the web app, the command line and the indexer always agree, ARIADNE fixes the parameters:

CIDv1 · sha2-256 · dag-pb directory · raw leaves · fixed chunks of 262 144 bytes · balanced layout with at most 174 links per file node · HAMT sharding above 256 KiB of links (links-bytes estimation, fanout 256) · links-first field order · no mode/mtime · hidden files excluded · the root is the directory itself.

In the web app your browser computes the CID with these parameters. To compute it yourself, there are two equivalent ways. With Node 22 or later and the script in the repository:

cd spec/fixtures
npm ci
node compute-cid.mjs /path/to/my-article

Or with Kubo 0.43.x, the reference IPFS implementation, on a fresh repository with no import profile:

ipfs init
ipfs add -r -Q --cid-version=1 --raw-leaves=true --chunker=size-262144 --hash=sha2-256 --max-file-links=174 --max-directory-links=0 --max-hamt-fanout=256 --pin=true ./my-article

Never use -w (--wrap-with-directory): it adds a second directory level and changes the CID. Both methods must print the same CID; the sample article committed in the repository, spec/fixtures/sample-article, resolves to bafybeidzsrohfscy7xlt4dh53j3kmlxunjl3r2354pvtfn6pysnjpmduna.

The 36 bytes on the blockchain

The text form of a CID (bafybei...) is for people. The blockchain stores its raw form, always 36 bytes:

Bytes	Value	Meaning
1	0x01	CID version 1
1	0x70	dag-pb: a folder (articles); reviews and comments use 0x55, a single raw file
2	0x12 0x20	the fingerprint is a sha2-256 hash, 32 bytes long
32	the digest	the fingerprint itself

The contract checks only this shape. It refuses any other version, codec or hash, any length other than 36 and a fingerprint made of zeros. It never reads IPFS: getting the content onto IPFS is the author’s job, and checking it is the indexer’s.

Who keeps copies

Copy	Who	How
First	the author	pinned with the author’s own pinning service or IPFS node, when publishing
Second	the ARIADNE indexer	pinned on its own IPFS node after it checks the content
Third	Zenodo, run by CERN	when the author gets a DOI, the Zenodo record holds the article’s files
Any number more	you, your institution, anyone	ipfs pin add <cid>

The author’s pin

Pinning at least one copy is the author’s responsibility. In the web app’s “Upload” tab you choose a pinning service and paste its key the first time:

• Filebase: a bucket on the IPFS network and its “IPFS RPC API” token, not the S3 access key and secret, which ARIADNE never needs.
• Pinata: an API key restricted to uploading files, pasted as its JWT. Pinata’s CAR uploads need a paid plan.

The key stays in your browser only, never on ARIADNE’s servers, and “Forget it” removes it. “Compute CID and pin” builds the folder in your browser, uploads it to your service as a CAR file (a package of IPFS blocks) and compares the CID the service stored with the one your browser computed; any difference stops the flow. Your reviews and comments are pinned the same way, with the same key.

You can also pin the folder yourself, on your own IPFS node or any pinning service, and paste its CID in the “I have a CID” tab. The app then downloads it through a public trustless gateway (https://trustless-gateway.link by default), checks every block against its hash and computes the CID again, so that gateway does not have to be trusted.

The indexer’s second copy

The ARIADNE indexer reads every new CID through its own IPFS node (Kubo). It pins every article it validated, and every review and comment text, as a second copy. This is an ordinary cost of running ARIADNE, not a fee for authors. What the node has pinned is recorded in a table that survives rebuilds, and if the node’s data were lost the indexer would pin every validated CID again. Content published on the previous TestNet application also stays pinned there.

The gateway: ipfs.ariadne.press

That same node serves a public gateway at https://ipfs.ariadne.press, which is where the web app loads an article’s figures and files from. It is deliberately limited:

• Only content it already holds. It never fetches arbitrary content from the IPFS network, so it cannot be used to serve anything ARIADNE has not checked and pinned.
• Only content paths. It answers /ipfs/<cid> and nothing else.
• Sandboxed, on its own origin. It runs on a separate address from the app, and its pages carry a security policy that runs no scripts.

Zenodo, a third copy

When an author gets a DOI (see Get a DOI with Zenodo), ARIADNE copies the article’s files into a Zenodo draft, checked against its CID (folders become folder__file names), together with a reading copy of the text. Once the author publishes it, the record is preserved by Zenodo, indexed by scholarly search engines, and cannot be deleted. On TestNet the drafts go to the Zenodo sandbox, whose test DOIs (10.5072/...) may be deleted at any time, so it is not a lasting copy.

Pin it yourself

Every article page shows its CID and the command to pin it. To keep a copy on your own computer or your institution’s server:

1. Install Kubo, the reference IPFS implementation.

2. Create its repository once with ipfs init.

3. Start the node with ipfs daemon and keep it online.

4. Pin the article:

   ipfs pin add <cid>

Your node fetches the folder from the nodes that hold it and keeps it from then on. Because the CID is the fingerprint, your copy is exactly the published version, and anyone fetching it from you can check that. Pin each version you want to keep; every version has its own CID.

If every copy disappears

Availability on IPFS and validity on the blockchain are separate things.

• The record stays. The article’s number, authors, fields, status, every version’s CID, its reviews, votes and comments remain on the blockchain. The article stays valid.
• The indexer says so. It marks the content as unavailable, shows the article with a warning instead of hiding it, and checks again periodically.
• Any surviving copy restores it. As soon as anyone who kept the files adds them to IPFS again, with the canonical parameters, they have the same CID, and the article is readable again. The CID proves it is the same text; nobody can put a different text in its place.
• If no copy survives anywhere, the text is lost, but the public record that it existed, its fingerprint and all its discussion remain.

That is why ARIADNE keeps several independent copies, and why a pin by you or your institution is always welcome.