Data Model

Due to Arweave's permanent, immutable nature traditional file system operations such as file/folder renaming and moving, and file updates cannot be done by simply updating the on-chain data model.

ArFS works around this by defining an append-only transaction data model and applying it to the tags used in the Arweave Transaction headers.

It utilizes a bottom-up data model (files refer to parent folder, folders refer their parent folder etc) to avoid race conditions in file system updates. A top-down data model would require the parent model (i.e. a folder) to store references to its children.

These defined entities allow the state of the drive to be constructed by a client to look and feel like a file system.

• Drive Entities contain folders and files

• Folder Entities contain other folders or files

• File Entities contain both the file data and metadata

Entity Types

Arweave transactions are composed of transaction headers and data payloads.

ArFS entities, therefore, have their data split between being stored as tags on their transaction header and encoded as JSON and stored as the data of a transaction. In the case of private entities, JSON data and file data payloads are always encrypted according to the protocol processes defined below.

• Drive entities require a single metadata transaction, with standard Drive tags and encoded JSON with secondary metadata.

• Folder entities require a single metadata transaction, with standard Folder tags and an encoded JSON with secondary metadata.

• File entities require a metadata transaction, with standard File tags and an encoded Data JSON with secondary metadata relating to the file.

• File entities also require a second data transaction, which includes a limited set of File tags and the actual file data itself.

Entity Relationship

The following Entity Relationship Diagram explains the high level relationships between drive, folder and file entities (and their associated data).

Entity Relationship Diagram

Metadata Format

Arweave File System Metadata stored in any Arweave transaction tags will be defined in the following manner:

Example-Tag: "example-data"

Metadata stored in the Transaction Data Payload will be JSON encoded in the following manner:

{
    "exampleField": "exampleData"
}

Fields suffixed with ? are optional.

Enumerated field values are defined in the format "value 1 | value 2".

All UUIDs used for Entity-Ids are based on the https://en.wikipedia.org/wiki/Universally_unique_identifier standard.

There are no requirements to list ArFS tags in any specific order.