❤
npm
Sign UpSign In

@skalenetwork/filestorage.js

1.0.1 • Public • Published

SKALE Filestorage.js

npm version Build Status codecov Discord

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.

Discord

License

GitHub

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

Readme

Keywords

Package Sidebar

Install

npm i @skalenetwork/filestorage.js

Repository

github.com/skalenetwork/filestorage.js

Homepage

github.com/skalenetwork/filestorage.js#readme

Weekly Downloads

3

Version

1.0.1

License

LGPL-3.0-only

Unpacked Size

11.1 MB

Total Files

48

Last publish

Collaborators

  • rikon
  • dmitrytk
  • cstrange
  • skalelabsdev
  • theskyunicorn
  • stebaev
  • l_sergiy
Try on RunKit
Report malware