ARIADNE publishing guide

This guide explains how to write an ARIADNE article, how it becomes the 36-byte content identifier (CID) that the blockchain stores, and how to publish it from the web app. The contract never reads IPFS: getting the content pinned is the author's job (ARIADNE_SPEC section 14.4); the ARIADNE indexer then keeps a second copy of everything it validates.

1. Three paths, one `publish()` call

Path	Who computes the CID	Who pins	Where
A — Upload in the web app	your browser, with the canonical parameters below	Filebase or Pinata, with your own key	`/publish`, tab "Upload"
B — I have a CID	you, with Kubo or the script in this repo	you (any pinning service or your own node)	`/publish`, tab "I have a CID"
C — CLI	`ariadne publish ./my-article`	same as A	M5

2. What a publication is

A publication is a folder with:

index.md, required: the text, in Markdown, starting with a header (section 3);
assets/, optional: figures, data files, anything the text refers to. Sub-folders inside assets/ are allowed.

Nothing else may sit next to index.md. Total size at most 20 MB; larger material goes in a separate dataset publication. No hidden files (names starting with a dot), no symbolic links. Use UTF-8 text with Unix line endings; the web app takes care of this when you write in the Upload tab. Avoid spaces in file names (fig-1.svg, not fig 1.svg).

Everything in the folder is public and permanent, including comments in the source () and every file in assets/. A new version adds a new folder; the old one stays readable.

3. The header (front-matter)

index.md starts with a header between two lines that contain only ---. The web app writes it from the publication form ("Fill the header from the form" updates it if you change the form later); you only need to write the title and the abstract.

---
title: "Heart-rate recovery after repeated sprints"
authors: ["YOUR_ADDRESS", "CO_AUTHOR_ADDRESS"]
field: 0x0303
secondary_field: 0x0501
type: article
parent: 0
abstract: "One paragraph that says what was done and what was found."
keywords: ["sprint", "heart rate, recovery"]
references: ["https://doi.org/10.1000/example"]
license: CC-BY-4.0
language: en
---

Key	Required	What it is	Checked against the chain
`title`	yes	the title shown on the article page and in the feed	no
`authors`	yes	Algorand addresses; the first is the wallet that publishes, then the declared co-authors	first address: yes; the rest: a notice only
`field`	yes	primary field, e.g. `0x0303` (the list is at `/fields`)	yes
`secondary_field`	no	second field, or 0 / absent for none; different from `field`	yes
`type`	yes	`article`, `notes`, `amendment`, `dataset` or `replication`	yes
`parent`	yes	0, except for an amendment: the number of the article it amends	yes
`abstract`	recommended	one paragraph, shown under the title in the feed	no
`keywords`	no	a list of words	no
`references`	no	a list of DOIs, URLs or CIDs, kept as data (not shown: write a visible References section too)	no
`license`	recommended	an SPDX licence name, e.g. `CC-BY-4.0`	no
`language`	recommended	language code, e.g. `en`, `es`	no

Rules of the header:

one key: value per line, in lower case, starting at the beginning of the line;
text in double quotes ("..."); inside it you may use :, # and commas, but not a double quote (use single quotes around the whole value instead: title: 'The "fast" protocol');
lists in brackets ["a", "b"], or one item per line below the key, each starting with two spaces and - ;
numbers in decimal (771) or hexadecimal (0x0303);
# outside quotes starts a comment until the end of the line.

If a checked value differs from what you declared on-chain, the article stays valid but is shown with a warning (ARIADNE_SPEC section 14.3); the web app refuses to sign until the header matches the form.

4. Writing the text

The text is Markdown (CommonMark with the GitHub extensions). The title comes from the header, so sections start at level 2 (##).

You write	You get
`## Methods`, `### Subjects`	section and sub-section headings
a blank line between paragraphs	separate paragraphs
a backslash `\` at the end of a line	a line break inside a paragraph
`italic`, `bold`, `~~struck~~`, `code`	emphasis, strong, struck-through, monospaced
lines starting with `-` or `1.`	bulleted or numbered lists (indent by two spaces to nest)
`- [ ] to do` / `- [x] done`	checklists
`> quoted text`	a quotation block
three backticks, then the language name, the code, three backticks	a code block (monospaced, without colours)
rows of cells separated by vertical bars, with a line of dashes under the first row	a table; colons in the dashes line align a column (`:---:` centred, `---:` right)
`a claim[^1]` and, anywhere, `[^1]: the note`	a numbered footnote, listed at the end of the article

Mathematics (LaTeX, rendered with KaTeX)

Inline: $E = mc^2$ .
Displayed (centred, on its own line): a line with only $$, the formula, a line with only $$:
```
$$
\int_0^1 x\,dx = \tfrac{1}{2}
$$
```
$$ ... $$ written on a single line comes out inline, not centred.
Most LaTeX mathematics works: fractions, roots, sums, integrals, Greek letters, \mathbb{R}, \text{...}, matrices (\begin{pmatrix} ... \end{pmatrix}), aligned equations (\begin{aligned} ... \end{aligned}).
Not available: $ ... $ and \[ ... \] as delimiters, equation numbers and \label/\ref, document-wide macros (\newcommand works only inside the formula where it is written).
A literal dollar sign is written \$. Subscripts and chemistry go in math: $\mathrm{H_2O}$ , $\dot{V}O_{2\,max}$ .

Figures

Put the file in assets/ and write:

![Figure 1: heart rate during the six sprints](assets/fig-1.svg)

*Figure 1.* Heart rate during the six sprints; the shaded band is the standard deviation.

The text in brackets is the alternative text (read aloud by screen readers, shown if the image cannot load); the paragraph below is the visible caption. SVG, PNG, JPG, GIF and WebP are shown; prefer SVG for charts and keep each image under a few megabytes. Images from other websites (https://...) are not embedded: they are shown as a link, because an external image can change, disappear or be used to follow readers.

What is not supported

HTML. Tags are ignored: in a sentence their text stays and the tag disappears (<sub>2</sub> becomes 2); a block of HTML such as <div>...</div> disappears with its content. There are no scripts, frames, embedded videos (link to the video instead), colours or fonts.
Links to a heading inside the text (#methods).
Showing files other than images inside the text: link them instead, [the protocol](assets/protocol.pdf).

Reviews and comments

Reviews and comments use the same Markdown and mathematics, in a single text of at most 256 KiB, without an assets/ folder: they cannot show images. They are pinned with the same key as your articles.

5. Co-authors

Co-authors are declared once, in the publish form, and can never be changed: at most 25 addresses, never your own. Check every address before signing. Each co-author later opens the article with their own wallet and confirms; from then on they can claim an equal share of the article's reputation (the votes are split in 1 + declared co-authors shares; you receive the rounding). A declared co-author who votes on or reviews the article can no longer confirm, and the share of a co-author who never confirms is never claimed by anyone. You pay one small storage deposit per declared co-author.

To find a co-author by their ORCID iD, type it under the co-author list: the form offers the addresses whose link to that iD is verified (see section 8b). The address is what gets declared; check it as any other.

6. Path A — Upload in the web app

Open /publish (TestNet: /testnet/publish), connect your wallet, choose the fields, the type and the co-authors.
In "Upload", write index.md (the template follows the type you chose) and add the files of assets/.
The first time, choose where your files are pinned and paste that provider's key:
- Filebase: create a bucket on the IPFS network, then Access Keys → IPFS RPC API → choose the bucket and generate a token. Paste that token (not the S3 access key and secret, which ARIADNE never needs).
- Pinata: API Keys → New key, restricted to uploading files (CAR uploads need a paid Pinata plan). Paste the JWT.
The key stays in your browser only (never on ARIADNE servers) and "Forget it" removes it.
"Compute CID and pin": your browser builds the folder with the canonical parameters, uploads it to your provider as a CAR file and compares the CID the provider stored with its own. Any difference stops the flow.
The cost (storage deposit + network fees) and the ALGO available in your account are shown; "Sign and publish" opens your wallet. Your account needs the cost plus the 0.1 ALGO every Algorand account keeps. On TestNet, ALGO are free at https://bank.testnet.algorand.network.

7. Path B — I have a CID

7a. Compute the CID without Kubo (Node >= 22)

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

Prints the base32 CID (bafybei...), its 36 raw bytes as hex (01 70 12 20 + sha2-256 digest) and the file list.

7b. Or with Kubo 0.43.x (reference implementation, fresh repo, 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). Both methods must print the same CID; the committed fixture /spec/fixtures/sample-article resolves to bafybeidzsrohfscy7xlt4dh53j3kmlxunjl3r2354pvtfn6pysnjpmduna.

7c. Pin it and paste it

Keep your Kubo node online (ipfs pin add <cid>), or upload the CAR to any pinning service that preserves the root CID. Then paste the CID in "I have a CID": the app downloads it as a CAR through a public trustless gateway (https://trustless-gateway.link by default), verifies every block against its hash, re-computes the folder CID, requires index.md, checks the header against the form and the size limit, and only then enables "Sign and publish".

Canonical 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.

8. After publishing

The indexer fetches the folder, validates it, pins a second copy and serves it through the ARIADNE gateway (a separate origin that only serves content ARIADNE holds). The article page shows the CID and the command to pin it yourself: ipfs pin add <cid>. Extra pins by you or your institution are always safe.
New versions (preprint and under review only) repeat Path A or B with the same header values; the token's ARC-19 reserve follows the current CID.
Reviews and comments are stored as a raw-codec CID (bafkrei...) and pinned the same way: through your provider key.

8b. Link your ORCID iD

On your profile (open it from the account menu), type your ORCID iD and sign the declaration (network fee only, no deposit). Then prove the iD is yours: sign in at orcid.org, and under Websites & social links add a link titled ARIADNE with the address of your profile that the page shows (for example https://ariadne.press/testnet/u/<your address>), visible to Everyone. The indexer reads your public ORCID record about every ten minutes during the two days after you link the iD, then weekly; once it finds the link, readers see the ORCID iD and your name from the record, and citations use that name. ARIADNE never derives reputation from ORCID. Unlinking hides the iD; the declaration stays in the chain history.

8c. Get a DOI with Zenodo

Accepted authors see DOI for this article under the article's CID.

Connect Zenodo. Zenodo asks you to let ARIADNE create drafts in your account (never publish). On TestNet this is the Zenodo sandbox, whose test DOIs (10.5072/...) may be deleted at any time.
Prepare a draft of the current version. ARIADNE copies the article's files (verified against its CID; folders become folder__file names), its title, abstract, keywords and licence, and the authors: the name of each verified ORCID record with its iD, else the name you type for the draft. The record says it is identical to the article page and to the version's CID, and is proposed to ARIADNE's community on Zenodo (ariadne-algo).
Publish it on Zenodo after checking it. A published Zenodo record cannot be deleted.
Declare the DOI back here (network fee only). The indexer checks the record and marks the DOI verified; citations then use it. Version 0 means "every version": Zenodo's concept DOI.

A later version of the article becomes a new version of your Zenodo record, under the same concept DOI. A DOI from another repository can be declared directly; DataCite DOIs are checked on MainNet, others are shown as declared by an author. If the article is retracted here, its DOI stays registered: edit the Zenodo description to say so.

9. From CID to the 36 on-chain bytes

publish(cid: byte[36], ...) takes the raw CIDv1 bytes: version 0x01, codec 0x70 (dag-pb), multihash prefix 0x12 0x20, then the 32-byte digest. In JavaScript: CID.parse(text).bytes (multiformats). In Python: multiformats.CID.decode(text). Only sha2-256 dag-pb directories are accepted for articles; reviews and comments use codec 0x55 (raw single file).

10. Costs

No platform fees for authors or readers. You pay Algorand network fees (fractions of a cent) and a storage deposit, held by the protocol, for the data you publish: about 0.21 ALGO for a publication (ASA + article box + your author box) plus 0.029 ALGO per declared co-author. The web app shows the exact amount, on the selected network, before your wallet opens.