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 git@github.com: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.