SKALE Filestorage.js

Javascript library which implements client for decentralized file storage on SKALE chains.

• Node.js v10, 12, and v14 support

Install

Run the following command:

npm i --save @skalenetwork/filestorage.js   

Usage

To use Filestorage.js you should have SKALE endpoint.

Example: http://some.local-or-remote.node:8546

Initiating of Filestorage

Construct new Filestorage object:

new Filestorage(web3Provider, enableLogs);

Parameters

| Parameter | Description | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | String | object web3Provider | URL of SKALE endpoint or one of the Web3 provider classes | | boolean enableLogs | (optional) Enable/disable console logs |

Example

Initialize with SKALE endpoint:

const Filestorage = require('@skalenetwork/filestorage.js');
let filestorage = new Filestorage('----SKALE ENDPOINT----');

Initialize with external web3 provider:

const Filestorage = require('@skalenetwork/filestorage.js');
const Web3 = require('web3');

const web3Provider = new Web3.providers.HttpProvider('----SKALE ENDPOINT----');
let filestorage = new Filestorage(web3Provider);

Using in HTML

To use filestorage.js in HTML you should import filestorage.min.js from npm package:

<script src="PATH_TO_PACKAGE/@skalenetwork/filestorage.js/dist/filestorage.min.js"></script>

Example:

<script src="PATH_TO_PACKAGE/@skalenetwork/filestorage.js/dist/filestorage.min.js"></script>
<script type="text/javascript">
    async function downloadFile() {
        let fs = new filestorage('----SKALE ENDPOINT----', true);
        await fs.downloadToFile('----STORAGEPATH----');
    }
</script>   

Upload file

Upload file using internal signing:

filestorage.uploadFile(address, filePath, fileBuffer, privateKey);

Upload file using external signing (Metamask, etc.):

filestorage.uploadFile(address, filePath, fileBuffer);

Parameters

| Parameter | Description | | ------------------- | ----------------------------------------------------------------- | | String address | Account address | | String filePath | Path of uploaded file in account directory | | Buffer fileBuffer | Uploaded file data | | String privateKey | (optional) Account private key, to sign transactions internally |

Returns

| Type | Description | | :------: | ------------------------------------------- | | String | Path of file in Filestorage |

Download file

Download file from Filestorage into browser downloads folder:

filestorage.downloadToFile(storagePath);

Parameters

| Parameter | Description | | -------------------- | ------------------------------------------- | | String storagePath | Path of file in Filestorage |

Download buffer

Download file from Filestorage into buffer

filestorage.downloadToBuffer(storagePath); 

Parameters

| Parameter | Description | | -------------------- | ------------------------------------------- | | String storagePath | Path of file in Filestorage |

Returns

| Type | Description | | :------: | ------------ | | Buffer | File content |

Delete file

Delete file using internal signing:

filestorage.deleteFile(address, filePath, privateKey);

Delete file using external signing (Metamask etc):

filestorage.deleteFile(address, filePath);

Parameters

| Parameter | Description | | ------------------- | ------------------------------------------------------ | | String address | Account address | | String filePath | Path of the file in account directory to be deleted | | String privateKey | (optional) Account private key, to sign transactions |

Create directory

Creates directory on the specific path. To create directory using internal signing:

filestorage.createDirectory(address, directoryPath, privateKey);

Create directory using external signing (Metamask etc):

filestorage.createDirectory(address, directoryPath);

Parameters

| Parameter | Description | | ---------------------- | ------------------------------------------------------ | | String address | Account address | | String directoryPath | Path of the directory to be created | | String privateKey | (optional) Account private key, to sign transactions |

Returns

| Parameter | Description | | -------------------- | ------------------------------------------------ | | String storagePath | Path of directory in Filestorage |

Delete directory

Deletes directory on the specific path. To delete directory using internal signing:

filestorage.deleteDirectory(address, directoryPath, privateKey);

Create directory using external signing (Metamask etc):

filestorage.deleteDirectory(address, directoryPath);

Parameters

| Parameter | Description | | ---------------------- | ------------------------------------------------------ | | String address | Account address | | String directoryPath | Path of the directory to be deleted | | String privateKey | (optional) Account private key, to sign transactions |

List directory

Lists content of the specific directory

filestorage.listDirectory(storagePath); 

Parameters

| Parameter | Description | | -------------------- | ------------------------------------------------ | | String storagePath | Path of directory in Filestorage |

Returns

Array of content. Each content could be file or directory.

Content Object for file contains:

| Field | Description | | -------------------------- | ------------------------------------------- | | String name | File name | | String storagePath | Path of file in Filestorage | | String isFile | Whether content is file | | number size | File size, in bytes | | number status | File uploading status | | number uploadingProgress | Upload progress, in percents |

Content Object for directory contains:

| Field | Description | | -------------------- | ------------------------------------------------ | | String name | Directory name | | String storagePath | Path of directory in Filestorage | | String isFile | Whether content is file |

Reserve space

Reserve space for certain address in Filestorage in bytes.

• Note: can be called only by ALLOCATOR_ROLE (or schain owner in v1 chains)

filestorage.reserveSpace(allocatorAddress, addressToReserve, reservedSpace, privateKey);

Reserve space using external signing (Metamask etc):

filestorage.reserveSpace(allocatorAddress, addressToReserve, reservedSpace);

Parameters

| Parameter | Description | | ------------------------- | ----------------------------------------------------------- | | String allocatorAddress | Address with ALLOCATOR_ROLE | | String addressToReserve | Address to reserve space for | | String reservedSpace | Reserved space in bytes | | String privateKey | (optional) sChain owner private key, to sign transactions |

Grant allocator role

Granting allocator role to be able to reserve space in Filestorage

• Note: can be called only by ADMIN_ROLE (on v2+ chains)

filestorage.grantAllocatorRole(adminAddress, allocatorAddress, adminPrivateKey);

Grant allocator role using external signing (Metamask etc):

filestorage.grantAllocatorRole(adminAddress, allocatorAddress, adminPrivateKey);

Parameters

| Parameter | Description | | ------------------------- | ----------------------------------------------------------- | | String adminAddress | DEFAULT_ADMIN address | | String allocatorAddress | Address to grant role for | | String adminPrivateKey | (optional) DEFAULT_ADMIN private key, to sign transactions|

Get reserved space

Get information about reserved space for account in bytes.

filestorage.getReservedSpace(address);

Parameters

| Parameter | Description | | ------------------------- | ----------------------------------------------------------- | | String address | Account address |

Returns

| Parameter | Description | | ---------------------- | ------------------------------------------------ | | Number reservedSpace | Reserved space in bytes |

Get occupied space

Get information about occupied (actually used) space for account in bytes.

filestorage.getOccupiedSpace(address);

Parameters

| Parameter | Description | | ------------------------- | ----------------------------------------------------------- | | String address | Account address |

Returns

| Parameter | Description | | ---------------------- | ------------------------------------------------ | | Number occupiedSpace | Occupied space in bytes |

Get total space in Filestorage

Get information about total space in Filestorage in bytes.

filestorage.getTotalSpace();

Returns

| Parameter | Description | | ---------------------- | ------------------------------------------------ | | Number space | Total space in Filestorage in bytes |

Get total reserved space

Get information about total reserved space (sum of all reserved spaces) in bytes.

filestorage.getTotalReservedSpace();

Returns

| Parameter | Description | | ---------------------- | ------------------------------------------------ | | Number reservedSpace | Total reserved space in bytes |

Development

Install

git clone [email protected]:skalenetwork/filestorage.js.git
cd filestorage.js
npm install

Testing

First of all, please create random files for testing:

npm run generate

To run tests locally you need environment variables defining two keypairs (account, foreign account):

• SKALE_ENDPOINT: SKALE endpoint
• SCHAIN_OWNER_PK: SKALE chain owner privatekey
• PRIVATEKEY: test account privatekey
• FOREIGN_PRIVATEKEY: second test account privatekey

Then execute:

npm test

Browser testing

Requirements to run chrome integration tests:

• Chrome v80

Required environment variables to run browser integration tests locally:

• SKALE_ENDPOINT: SKALE endpoint
• SCHAIN_OWNER_PK: SKALE chain owner privatekey
• PRIVATEKEY: test account privatekey
• FOREIGN_PRIVATEKEY: second test account privatekey
• SEED_PHRASE: seed phrase to run metamask tests
• METAMASK_PASSWORD: password to run metamask tests (> 7 chars)

Run tests:

npm run test test/browser

Build a dist version

npm run minify

Publishing on npm:

npm publish

Versioning

The version scheme for this repo is {major}.{minor}.{patch}. For develop version scheme is {major}.{minor}.{patch}-develop.{number} For beta version scheme is {major}.{minor}.{patch}-beta.{number}

For more details see: https://semver.org/

Lint

Conforming to linting rules is a prerequisite to commit to filestorage.js.

npm run lint

Notes

Storage path

Storage path is a label used to point to file or directory in Filestorage. It contains 2 parts through slash:

1. File owner address (without 0x)
2. File/directory path in owner's root directory

Example:

77333Da3492C4BBB9CCF3EA5BB63D6202F86CDA8/directoryA/random_text.txt
77333Da3492C4BBB9CCF3EA5BB63D6202F86CDA8/random_text.txt
0x77333Da3492C4BBB9CCF3EA5BB63D6202F86CDA8/random_text.txt #Invalid storagePath

Contributing

If you have any questions please ask our development community on Discord.

License

All contributions are made under the GNU Lesser General Public License v3. See LICENSE.