ar.io DocumentationArFS Protocol
Arweave File System, or "ArFS" is a data modeling, storage, and retrieval protocol designed to emulate common file system operations and to provide aspects of mutability to your data hierarchy on Arweave's otherwise permanent, immutable data storage blockweave.
Due to Arweave's permanent, immutable and public nature traditional file system operations such as permissions, file/folder renaming and moving, and file updates cannot be done by simply updating the onchain data model.
ArFS works around this by implementing a privacy and encryption pattern and defining an append-only transaction data model using tags within Arweave Transaction headers.
Key Features
File Structure
ArFS organizes files and folders in a hierarchy. A file is two transactions: its data, and a metadata transaction that names the file and its parent folder. A folder is a metadata transaction only. Each file and folder points to its parent, so a client builds the hierarchy from the bottom up.
Metadata
Each file and folder has associated metadata, such as the name, type, size, and modification timestamp. ArFS uses Arweave's tagging system to store this metadata in a standardized format, which allows for easy querying and organization.
File Permissions
ArFS supports public and private drives. Anyone can read a public drive. A private drive is encrypted with AES-256 under keys derived from the owner's wallet signature and a drive password, so only someone holding the drive key, or one file's key, can read it. See Privacy & Encryption.
File Versioning
ArFS keeps every version of a file. A new version is a new metadata transaction with the same File-Id, and every earlier version stays on Arweave.
Search and Discovery
Arweave GraphQL gateways index ArFS tags such as Drive-Id, Folder-Id, File-Id and Entity-Type, so a client can find a drive's entities by query. Names and other JSON metadata are in the transaction data, not in tags, so a client searches them after it has read the drive.
Interoperability
ArFS is designed to be interoperable with other decentralized applications and services built on the Arweave network. Different applications and users can therefore work with the same files.
Getting Started
To start using ArFS, you'll need to familiarize yourself with the Arweave ecosystem, acquire AR tokens to cover storage costs, and choose a compatible client or library to interact with the ArFS protocol.
ArFS Version History
| Version | Date | Release Notes |
|---|---|---|
| 0.10 | August 2020 | The brief, beta version that was in use during initial testing of ArDrive across Web (Dart) and legacy CLI (Typescript). |
| 0.11 | September 2020 | Includes all of the major functionality supporting file systems on Arweave including new drives, folders, files, renames, moves and privacy. |
| 0.12 | December 2022 | Added Snapshot entities to support quick synchronization of drive state. |
| 0.13 | August 2023 | Added pins |
| 0.14 | January 2024 | Added isHidden property to file and folder metadata to enable clients to "hide" content from end users. |
| 0.15 | May 2025 | Added Drive-Signature entity type and Signature-Type metadata property on Drive entities. |
Drive State entities are tagged ArFS: "0.15" and did not change the version. A client that does not read them is unaffected.
Next Steps
Ready to dive deeper into ArFS? Here's what you should explore next:
- Entity Types - Understand the different ArFS entities and their structure
- Data Model - Learn how ArFS organizes data hierarchically
- Privacy & Encryption - Secure your data with private drives
- Creating Drives - Get started with your first ArFS drive
- Reading Data - Query and retrieve your ArFS data
Resources
For more information, documentation, and community support, refer to the following resources:
How is this guide?