Skip to main content

Creating a Virtual File System


This functionality is currently in development and may or may not be modified in the upcoming releases.

Whenever the Coinweb VM encounters a Call [hash] operation, it is tasked with calling a smart contract. Meanwhile the arbitrary hash value equals the smart contract id AND as well equals the merkleized hash of the constructed VFS for the specified smart contract.

Calling a smart contract using the Call operation puts the responsibility of the developer to construct a virtual file system (VFS) that has the identity of the smart contract that is called.

To make it more concrete, if a transaction contains the operation Call 0x1234, the Coinweb VM will try to find and execute the referenced smart contract. Implicitly the virtual machine has to mirror the virtual file system of the contract in order to execute. It is in the hands of the developer to find a way to construct a VFS that has the merkleized hash that equals 0x1234, for the Call operation to not abort the transaction. In the end this can be done by explicitly providing the ContractTree, by self-registration of the contract and a resulting embedded ReadOp, or in more complex scenarios by registering a contract that calls other contracts that set up the VFS.

General Structure of the VFS

The overall structure of the virtual file system is a combination of file paths and descriptions, mapped to hashes. The hashes represent the file content and are generated by another smart contract called data_hasher. It is responsible for referencing hashes and file contents in the claims database when the smart contract is being deployed to Coinweb.

File Path

A file path is represented by an array of path segments.

export type FilePath = { path: string[] };

const exampleFilePath = { part: ['example', 'path', 'to'] };

File Description

A file description includes a name and a file path.

export type FileDescription = { name: string; path: FilePath };

const exampleFileDescription = { name: 'file.js', path: exampleFilePath };

VFS (Contract Tree)

The contract tree is the virtual file system for a smart contract expressed as paths mapped to hashes. For a deployed smart contract the hashes are typically stored as claims by the data-hasher smart contract.

export type ContractTree = [FileDescription, HexString][];

const exampleContractTree = [
[exampleFileDescription, '0x012345...'],
[exampleFileDescription_2, '0x6789...'],

Resolved VFS (Contract Tree Resolved)

A resolved contract tree, the same virtual file system mapping as the ContractTree type, but contains the actual file contents. The data-hasher smart contract is responsible for the resolution of the actual file contents and their related hashes.

export type ContractTreeResolved = [FileDescription, Uint8Array][];

const exampleContractTreeResolved = [
[exampleFileDescription, new Uint8Array('file contents for 012345...')],
[exampleFileDescription_2, new Uint8Array('file contents for 6789...')],