EIP-5555: Ethereum Virtual Machine File System

Simple Summary

This document proposes a standard for an Ethereum file system and internet protocol.

Abstract

This document proposes a new, independent and neutral interoperable Ethereum Virtual Machine compatible file system standard made available in 2024 under the GNU Affero General Public license version 3 on Github by The Martian Company, with latest updates distributed on the Ur application store, which depends on the file system to provide its basic functionality.

Motivation

The Martian Company needed an undeletable file system implementation for the Human Instrumentality Project (HIP) in order to bootstrap the DogeOS and Life OS-like software collections of software.

The Martian Company has long waited (2012) for anybody to publish or propose a working and practical implementation of a permissionless undeletable file system written on and accessed through URIs similar to HTTP ones.

The Martian Company considers relevant that million dollars expensive 1 megabyte-sized rose picture written on the Bitcoin blockchain which to write now would cost many countries GDP in the series of events leading to its formation and to this proposal.

To The Martian Company staff cryptocurrency software always seemed more or less a pretty rough social contract centered around storing a bounded linearly increasing binary blob one gets to write after passing a spam filter.

Keeping this into consideration, in particular after the publication of the Ethereum software, which makes relatively straightforward bootstrapping and accessing differently speed size increasing networks per-device size class and defining data structures on them, The Martian Company was very happy when there has been talk of providing a file system to developers and users, but after waiting for another two years no work seemed to have still been published in that direction, so they they took on themselves the burden a working and easy to use and to understand implementation.

This proposal is necessary because The Martian Company's implementation of an Ethereum file system already works, it's already deployed on around 10% of all the couple thousands permissionless public Ethereum network bootstraps, it has has a total writing speed of around 100 kilobytes per second as of December 2025 and it's tens of gigabytes sized, so it starts to feel embarassing not to write this EIP.

The Martian Company doesn't think there's much to argue about why it's useful to have a working permissionless file system implementation and deployment available but since they are asked to argue here's some arguing:

• The Martian Company has read statements of Ethereum ecosystem defining itself a "world computer".

  Now how can one even consider that statement seriously if in 10 years nobody has made so they had any file in any directory on any world computer anywhere?

  Files and directories are basic components in computer programs.

  If Ethereum is a computer, then Ethereum must have a files, directories implementation in order for standard computer programs to access local hardware.

• Up so far, seemingly by design choice, the Ethereum project has made so Ethereum software deployers need to store contracts data off-chain in order to verify the safety and the authenticity of ethereum applications, which is defined in EIP-3091.

  The Martian Company never saw any reason not to store contracts source and even whole Etherum source on Ethereum networks (Solidity source code has already been written on the file system), so they've used the EVMFS to also write an implementation for an on-chain contracts sources, bytecode and ABI publishing standard, which is already integrated in contract deployer. provided for references purposes.

• The EVMFS has made possible to make OpenPGP compatible with Ethereum.

• The EVMFS named file system structure is literally Git on Ethereum.

• Anybody who doesn't want to know how ethereum works should still be able to publish uncensorable unstoppable complex applications written in any programming language easily.

• Where people should store files and resources for unstoppable applications in order to be sure they won't disappear after they die, on the moon?

• How does even produce a trustable robot if it one does not make it available a safe place where to store and update itself?

• The Martian Company sees no decentralized app nowhere in the Ethereum ecosystem except than their own, because they both interact and reside on the file system, even if they may still need access to external permissioned expensive computational resources, depending on what they do.

  The existing ones are not decentralized apps, but rather websites calling themselves applications, not computer applications.

  Computer applications are an object one must be able to easily adapt to run on any machine portably, which should be self-contained and modular, and conveniently hide most of its inner complexity to its authors and users.

  In this context the Ur is a best effort attempt at how The Martian Company sees users, web developers and application developers can publish and obtain applications for a world computer after 15 years of supposedly permissionless operating system maintainership. The OS-like collections of software they are included, Life and DogeOS are The Martian Company take on how to implement an operating system for a world computer, which is not the same as a personal computer, as in an individual can't unplug a world computer.

Specification

Version 1.0 of the file system is specified in three very short classes, FileSystem, LengthLock and CrossChainFileSystem split in same-named three source files.

There is no particular reason they are not merged in a single class and file except than they have been written, deployed and published at different times and because if the specification is good then it should also be easily decomposable so it seemed appropriate to have a version of the standard being easily extendable.

The evmfs file system reference implementation is an EVM Library application, which makes calls to newer versions of any of the contract seamless.

Global namespace and named tree

Basic file system functionalities are implemented by defining per user a global unnamed root directory, the global namespace in which files are accessed through their hash sums, evaluated with a cryptographically secure hash function, by default SHA256, and a named tree which root can only contain Ethereum-compatible git repositories.

In order to retrieve public files in a named tree using their hashes, every hash of every file at every commit is made accessible in the global namespace.

The choice of using the Git software specifically to provide this functionality has been dictated by time and because it's the best available tool The Martian Company is aware which seems fit for a file system which is supposed not to waste writing cycles, it natively supports OpenPGP so that it lets one easy provide repository access control and forces people to keep their files and directories in shape.

Address structure

A full EVMFS address in the global namespace has the following structure

evmfs://<chain-id>/<fs-address>/<user-address>/<file-hashsum>

where

• chain-id is an Ethereum network chainID,
• fs-address is a deployment of any exact version of the FileSystem contract file,
• user-address is an externally owned account (EOA) or a contract,
• and file-hashsum is the hashsum of a file.

Files can be encoded in any format specified by the standard.

Currently is foreseen no strict enforcing of any encoding format so the specification foresees to add fields in order for authors to specify the encoding.

By default files are encoded in base64, split in 22.000 characters strings and written in

(address namespace,
 string hashsum,
 uint256 index) => string chunk

Lower than 22.000 characters split have been set-up for specific networks in the implementation but The Martian Company supposes it's possible to dynamically evaluate max characters to be written in a single transaction on any network at any time.

String chunks are read-write until locked. The clients implementing the protocol must reject and warn users if they detect any unlocked chunk.

The exact amount of string chunks for a file. Chunks amount for a file are accessed through the LengthLock contract.

The length is accessed through mappings of the type

(address fs-address,
 address namespace,
 string hashsum) => uint256 length

Since version 1.0 of LengthLock mapping does not include the encoding, in order to extend the specification without breaking compatibility with existing code, its value will be the one accessed by the Encoding extension contract which will add support for specifying different encodings and split sizes for the same file.

A named tree file address in a tree has the form

evmfs://<chain-id>/<fs-address>/<namespace>/<git-repo-name>/<directory./<subdirectory>/.../<file-name>

For global namespace links, all fields except the hash can potentially be omitted for publicly accessible files. No default namespace resolving method is currently specified as it's resolving is very context and application specific.

The reference implementation defaults to user own's address and then to the public files list.

Implementation

The implementation is written in Bash, Javascript and Solidity and it depends on The Martian Company's LibEVM and EVM Toolchain SDK packages.

The non-latest versions of the reference evmfs program and all the tools needed to build and use it have been released under a a copyleft license in HTTP in Github in order for this EIP to be opened.

Latest versions of the reference clients and its dependencies, of which show of purchase is needed in order to peacefully contribute to the project, as The Martian Company is free as in freedom but not as in free beer, are only made available on the Ur user repository.

Notes

Until formal inclusion all the text in this document must be intended as a working draft which can be updated at any time by their authors and upon peer reviewing received from the EIPs Github's merge request page or other source.

Copyright

Copyright and related rights waived via GNU Affero General Public License version 3.