You can see the bcdocs for getting information about schemas of transactions described here.
Create the drive
First of all, a user (owner) 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 replicators. 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 replicator 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 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 replicators joined. Also, he determines that 100% signatures (percentApprovers) are needed to accept the transaction. And every 1 month (billing period) 4000 SO (billingPrice = replicas*driveSize) will be distributed between replicators by the formula.
Join to the drive
Any user (replicator) 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 owner. 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 replicators provides a better quality of Cross Verification. Over time, any number of replicators could join the Drive contract. A new replicator that joins when the Drive has no file may move to the standby mode. In the general case, the time of joining the replicator has to fill its memory with all files in the current state of the Drive. For this purpose, the replicator can get the root hash of the Drive from Blockchain and download files from another replicator (it must put a deposit for each downloaded file). If some replicator 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 replicators joined, the Drive state changes to the Pending and billing period starts.
One of the replicators 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. Replicators 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 owner 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 owner makes any file operation, it changes a root hash. Blockchain is storing this hash and anyone can get an actual hash. So, all replicators 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 owner 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 owner account to Drive account. These tokens are rewards of replicators and the owner for file spreading (the owner can also return part of its tokens). The transaction can be rejected in the following cases:
- if the owner doesn't have enough money;
- Blockchain already contains the same hash;
- not enough space on the Drive. Blockchain marks all replicators that they don't put deposits for a new file.
After the download of the file, replicators 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 replicator fails verification, Blockchain transfers the replicator'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, replicators won't store this file (they must also delete the relevant receipts (see Fair Streaming protocol)), in this case, all replicators will have the same files on the Drive and they all can pass verification.
When the owner wants to remove files from the Drive, it transfers the transaction with hashes of removed files. All replicators remove these files and Blockchain returns the deposits of replicators for this file back (If replicator 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 owner 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 owner 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.