FairOS dfs protocol explanation

Pod - could be compared with logical drive (​​https://docs.fairos.fairdatasociety.org/docs/fairOS-dfs/introduction, https://docs.fairos.fairdatasociety.org/docs/fairOS/architecture).

How is the Pod list stored in Swarm?

topic = bmtHashString('Pods')

# if you want to upload a new version of pods list, you need to calculate new epochLevel with current time
id = ContentAddressedChunk(topic, epochTime, epochLevel) 

# pods list. If you want to add or remove a pod, you need to modify this content. Indexes are used for getting new wallet with derivation path
content = 'pod_one,1' + "\n" + 'pod_two,2'

# upload pods list with user's account private key
SingleOwnerChunk.upload(accountPrivateKey, id, content) 

*epochTime, epochLevel are described in https://www.ethswarm.org/The-Book-of-Swarm.pdf page 249

Directory - way of organizing content. A directory can contain nested directories and files. Each directory has its own parent.

The very first directory has the following metadata. It is required for every Pod. Without it, a pod is not considered valid.

{
    "Meta": {
      "Version": "1",
      "Path": "",
      "Name": "/",
      "CreationTime": "1650893382",
      "ModificationTime": "1650893382",
      "AccessTime": "1650893382",
    },
    "FileOrDirNames": null,
  }

Metadata should be uploaded as SOC with private key received with derivation path (m/44'/61'/0'/index) and index tied to the pod.

# topic is hashed root path symbol
topic = bmtHashString('/')

# root directory metadata could be updated with epochTime and epochLevel
id = ContentAddressedChunk(topic, epochTime, epochLevel) 

# metadata is json that described above. Upload metadata with private key received by derivation path and `index`
SingleOwnerChunk.upload(podPrivateKey, id, metadata) 

The following directory (for example "HelloWorld") will have the root directory as its parent and have the following metadata.

{
    "Meta": {
      "Version": "1",
      "Path": "/",
      "Name": "HelloWorld",
      "CreationTime": "1650893382",
      "ModificationTime": "1650893382",
      "AccessTime": "1650893382",
    },
    "FileOrDirNames": null,
  }

Uploading metadata of the new directory

# topic is hashed full path of directory
topic = bmtHashString('/HelloWorld')

# metadata could be updated with epochTime and epochLevel
id = ContentAddressedChunk(topic, epochTime, epochLevel) 

# metadata is json that described above. Upload metadata with private key received by derivation path and `index`
SingleOwnerChunk.upload(podPrivateKey, id, metadata) 

If you are adding a file or directory, then the parent's metadata must be updated inside the FileOrDirNames field, the name of the file or directory must be added, prefixed with _F_ or _D_ respectively.

New root metadata

{
    "Meta": {
      "Version": "1",
      "Path": "",
      "Name": "/",
      "CreationTime": "1650893382",
      "ModificationTime": "1650893382",
      "AccessTime": "1650893382",
    },
    "FileOrDirNames": ["_D_HelloWorld"],
  }

File - binary data that the user wants to upload to the system. The file is divided into blocks of N bytes (block_size), and each block is uploaded as a separate array of bytes. Optionally, each block can be compressed. After each block of data is uploaded, the resulting swarm reference is added to the blocks metadata.

Then a set of blocks with swarm references is uploaded as a set of bytes into the swarm. Received reference of blocks stored is stored in the file's general metadata (in file_inode_reference).

{
  "version": "1",
  "user_address": [123,123,12,1],
  "pod_name": "pod_one",
  "file_path": "/",
  "file_name": "hello.txt",
  "file_size": "10",
  "block_size": "1000000",
  "content_type": "",
  "compression": "",
  "creation_time": "1650893382",
  "access_time": "1650893382",
  "modification_time": "1650893382",
  // base64 encoded swarm reference
  "file_inode_reference": "KNPeilXXVD+m8uSBnoBunStOGZlwOmMjLwqoEm/SRmg="
}

Uploading metadata of a file

# topic is hashed full path of directory
topic = bmtHashString('/hello.txt')

# metadata could be updated with epochTime and epochLevel
id = ContentAddressedChunk(topic, epochTime, epochLevel) 

# metadata is json that described above. Upload metadata with private key received by derivation path and `index`
SingleOwnerChunk.upload(podPrivateKey, id, metadata) 

Blocks - a set of meta-information in the form of a JSON string about the uploaded blocks of the file. The meta-information is uploaded into the swarm, and the resulting swarm reference is set in the general information about the file, so that the initial file can be assembled from the blocks.

{
  "Blocks": [
    {
      "Name": "block-00000",
      "Size": "17",
      "CompressedSize": "17",
      // base64 encoded swarm reference of uploaded block
      "Reference": {
        "R": "KNPeilXXVD+m8uSBnoBunStOGZlwOmMjLwqoEm/SRmg="
      }
    }
  ]
}