You can see the bcdocs for getting information about schemas of transactions described here.
Create the drive
First of all, a user (Storage Director Node) needs to create a new multisig account that will be used as the Drive account. To create the Drive, the owner must define the desired properties. After Drive creation, it should transfer the sufficient amount XPX to the drive’s balance. These mosaics will be exchanged to SO by Storage Replicator Nodes. When the Drive has been created it has NotStarted state. The Drive preparation has no strict time bounds. It is just an initiation of the Drive storage contract. Any Storage Replicator Node can join it at any time, and their reward will be calculated by the formula (reference). For each new Drive user must create a new multisig account.
The owner creates Drive in MB but Blockchain saves size like count of files blocks. One MB equals to 4 file blocks.
The example: A user wants to create a new 1000MB (driveSize) Drive for 12 months (duration). For this, he determines that he wants 4 replicas, but the Drive can start when 3 Storage Replicator Nodes joined. Also, he determines that 100% signatures (percentApprovers) are needed to accept the transaction. And every 1 month (billing period) 16000(1000*4(1MB=4 file blocks)*4(replicas)) SO (billingPrice = driveSize*replicas) will be distributed between Storage Replicator Nodes by the formula. Every joined replicator will make deposit equal to drive size in file blocks. If drive size is 1000MB than replicator will deposit 1000*4(1MB=4 file blocks) SO.
Join to the drive
Any user (Storage Replicator Node) may agree with the Drive offer and send the join transaction. With this transaction, the deposit (SO; equals to Drive size) is automatically debited from the Storage Director Node. If there is not enough SO, its join transaction will reject. This deposit will be blocked until the end of the Drive.
A group of nReliable Storage Replicator Nodes provides a better quality of Cross Verification. Over time, any number of Storage Replicator Nodes could join the Drive contract. A new Storage Replicator Node that joins when the Drive has no file may move to the standby mode. In the general case, the time of joining the Storage Replicator Node has to fill its memory with all files in the current state of the Drive. For this purpose, the Storage Replicator Node can get the root hash of the Drive from Blockchain and download files from another Storage Replicator Node (it must put a deposit for each downloaded file). If some Storage Replicator Node joins to Drive later, its final reward will be calculated considering its time of joining. Replicator reward depends on the time of joining the Drive. For the earlier joining, the reward is greater. When the minimal count of Storage Replicator Nodes joined, the Drive state changes to the Pending and billing period starts.
One of the Storage Replicator Nodes becomes the primary, according to consensus, and it creates the transaction for exchange of XPX to SO in the Drive account. If the sum on balance is sufficient, Drive contract starts up, the state of the Drive is changed to InProgress, and the contract is going to start. Storage Replicator Nodes obtain rewards every billing period automatically. They also initiate a new XPX to SO exchange after the end of the billing period.
Interacting with drive
During the execution of the Drive, the Storage Director Node can interact with it, like on other cloud storage. It means that it can do uploading, removing, renaming, moving, downloading files, and creating/removing directories. All commands create the new Drive file system. Whenever an Storage Director Node makes any file operation, it changes a root hash. Blockchain is storing this hash and anyone can get an actual hash. So, all Storage Replicator Nodes can easily monitor Drive changes.
The new Drive file system transaction has the following properties:
- Drive key
- The modifiable drive's key.
- New root hash
- The new hash of a local Drive.
- Old root hash
- The hash of the local Drive before changes.
- Add actions
New added files. It is an array of structures that consists of:
- File size
- File hash
- Remove actions
Removed files. It is an array of structures that consists of:
- File size
- File hash
When an Storage Director Node uploads new files, it fills the addActions array, where indicates the file hashes and sizes. Blockchain automatically transfers fileSize * replicas SM for each file from the Storage Director Node account to Drive account. These tokens are rewards of Storage Replicator Nodes and the Storage Director Node for file spreading (the Storage Director Node can also return part of its tokens). The transaction can be rejected in the following cases:
- if the Storage Director Node doesn't have enough money;
- Blockchain already contains the same hash;
- not enough space on the Drive. Blockchain marks all Storage Replicator Nodes that they don't put deposits for a new file.
After the download of the file, Storage Replicator Nodes must send the transaction with hashes of downloaded files. Blockchain locks SM equal to fileSize of each file until the file is removed. The deposit is used as a guarantee of saving. When the Storage Replicator Node fails verification, Blockchain transfers the Storage Replicator Node's deposits to the Drive account. If the owner lies and the size of the file is not equal to the size in the transaction, Storage Replicator Nodes won't store this file (they must also delete the relevant receipts (see Fair Streaming protocol)), in this case, all Storage Replicator Nodes will have the same files on the Drive and they all can pass verification.
When the Storage Director Node wants to remove files from the Drive, it transfers the transaction with hashes of removed files. All Storage Replicator Nodes remove these files and Blockchain returns the deposits of Storage Replicator Nodes for this file back (If Storage Replicator Node didn't put a deposit for file, Blockchain will not return anything). Blockchain will reject the transaction if it contains file hashes of not existing files.
Only the root hash is changed, because these operations don't require the transfer of data (metadata is still sent, but it requires less space).
The Storage Director Node can prolong a Drive with increasing or decreasing its duration. For example, a user has a Drive with a duration of 12 months, but the Storage Director Node decides to increase the duration to 36 months. In this case there is a need to make the transaction that contains the prolong 24 months.
- The Storage Director Node decides to terminate the Drive.
- The Drive does not have money to start the next billing period (in this case, the Drive will be terminated by Storage Replicator Nodes). After the end of the Drive duration, all Storage Replicator Nodes return their deposits and get rewards (see Finished state).