@arcana/storage v0.3.16

Arcana Storage

Installation

Using npm/yarn

npm i @arcana/storage
yarn add @arcana/storage

You can use the standalone module which includes the polyfills.

<script src="./dist/standalone/storage.umd.js"></script>

import { StorageProvider } from '@arcana/storage/dist/standalone/storage.umd';

Storage SDK Usage

Initialize

// address: Smart contract address of app
// provider: Web3provider (Eg: If you have installed metamask then window.ethereum will work)
//           Default value of provider is window.ethereum
// appId: This field is optional. If you want to download a file with just did then you won't require this field
const arcanaInstance = new arcana.storage.StorageProvider({ appId, provider, email });

Get Uploader

const Uploader = arcanaInstance.getUploader();
// file: Blob format
Uploader.upload(file);

Get Downloader

const Downloader = arcanaInstance.getDownloader();
// did: DID of file which you want to download
Downloader.download(did);

Get Access

const Access = arcanaInstance.getAccess();

Share a File

// did: DID of file to be shared, can be a hexadecimal string or an array of such strings
// address: recipients address, similar type as "did"
// validity (optional): For how long will be the user able to download the file, e.g. [400] would mean 400 seconds.
Access.share(did, address);

Revoke File Sharing

// did: DID of file from which access is removed
// address: Address of the user who's access is getting revoked
Access.revoke(did, address);

Transfer File Ownership

// address: new owner's address
Access.changeFileOwner(did, address);

Delete a File

Access.deleteFile(did);

Storage Usage Metrics

Get Upload Limit

//Get consumed and total storage of the current user
let [consumed, total] = await Access.getUploadLimit();

Get Download Limit

//Get consumed and total bandwidth of the current user
let [consumed, total] = await Access.getDownloadLimit();

List Shared Files

List files that are shared with the current user.

let files = await arcanaInstance.sharedFiles();

List Uploaded files

List files that are uploaded by the current user.

let files = await arcanaInstance.myFiles();

Download File by DID

Note: No appID is required to download a file using the file DID. The file DID is returned at the time of file upload and uniquely identifies the file.

// Pass the provider if required otherwise it will choose window.ethereum by default
let arcanaInstance = new arcana.storage.StorageProvider();
await arcanaInstance.downloadDID('<did of the file>');

NFT

Create Metdata URL

Note: This is typically used for NFT use case.

let metadata = await arcanaInstance.makeMetadataURL(
  title,
  description,
  did,
  file,
);
console.log(metadata)
// https://test-storage.arcana.network:9000/api/v1/metadata/0x129d1438ff3bf014e9b9094b3a5d410f691c208ed5305b0844307b761c0e295e

You can use this URL to mint your NFT

Link NFT with did

Note: After minting NFT inorder to use this NFT as a private NFT you need to link it with did

let chainId = 80001,tokenId  = 3, nftContract = "0xE80FCAD702b72777f5036eF1a76086FD3f882E29"
    await arcanaInstance.linkNft(did, tokenId, nftContract, chainId); 

CallBack Functions

1. Upload

1.1 On Success

Uploader.onSuccess = () => {
  console.log('Completed file upload');
};

1.2 On Progress

Uploader.onProgress = (bytesUploaded, bytesTotal) => {
  console.log("Percentage completed", (100*bytesUploaded)/bytesTotal)
};

2. Download

2.1 On Success

Downloader.onSuccess = () => {
  console.log('Completed file download');
};

2.2 On Progress

Downloader.onProgress = (bytesDownloaded, bytesTotal) => {
  console.log("Percentage completed", (100*bytesDownloaded)/bytesTotal)
};

Basic Error Handling

During file upload or file download operations, if there are any errors, dApp developers can address those by catching the exception raised by the Storage SDK:

import { StorageProvider } from '@arcana/storage/dist/standalone/storage.umd';

dAppStorageProvider = new StorageProvider({
        appId: ARCANA_APP_ID,
        provider: window.ethereum,
        email: user_email_string,
      });

const uploader = await dAppStorageProvider.getUploader();

uploader.upload(fileToUpload)
  .catch((error) => {
    if (error.message === NO_SPACE) {
      ...
    } else if (error.code === UNAUTHORIZED) {
      ...
    } else {
      ...
    }
  });

Advanced Error Handling

This advanced error handling section is only meant for file upload to address special dApp use cases. It is recommended that dApp developers using Exception handling - catch mechanism, for handling file upload errors.

Every user action to upload a file internally results in the Storage SDK splitting the file into multiple parts according to the tus protocol. These parts are uploaded to the Arcana Store. If any of the file segment fails to transmit, it is automatically retried until all file segments are transferred. The automatic retry counter is hard coded to '5' in the beta release and the dApp developer cannot change this configuration.

If the dApp developer is required to handle file upload error in case the retries fail, use onError() mechanism. After retrying for four times, in case of any segment upload fails for the fifth time, the Storage SDK invokes onError() callback to enable dApp developer to take appropriate action or delay file transfer to deal with intermittent network failures.

Uploader.onError = (err) => {
  console.log('Error', err);
};

Changing Network and Wallet Account

Change Network

// Below is default function, which can be modified by the developers
arcanaInstance.onNetworkChange = (oldNetwork, newNetwork) => {
  window.location.reload()
}

Change Account

// Below is default function, which can be modified by the developers
arcanaInstance.onAccountChange = (accounts) => {
  window.location.reload()
}

Storage SDK Error Messages