ethoFS SDK

Official NodeJS SDK for ethoFS

Overview

The ethoFS NodeJS SDK provides the quickest / easiest path for interacting with the Etho Protocol Network.

Installation

npm install --save @ethofs/sdk

Setup

To start, simply require the ethoFS SDK and set up an instance with your ethoFS Upload Address/Key (Etho Protocol Key). Register a new upload address using the addUser function or by registering at: Etho Protocol Uploads.

Initialization Without Authentication

const ethofsSDK = require('@ethofs/sdk');
const ethofs = ethofsSDK();

Initialization With Authentication

const ethofsSDK = require('@ethofs/sdk');
const ethofs = ethofsSDK('yourETHOPrivateKey');

Initialization With Custom RPC/Gateway Locations

Params

• connections : A JSON object that contains the following keyvalues:
  • rpc (optional) : The Etho Protocol RPC Location
  • gateway (optional) : The IPFS API/Gateway Location

Example Code

const connections = {
    rpc: 'https://rpc.ethoprotocol.com',
    gateway: 'https://gateway.ethoprotocol.com'
};
const ethofsSDK = require('@ethofs/sdk');
const ethofs = ethofsSDK('yourETHOPrivateKey', connections);

Quickly test that you can connect to the API with the following call:

ethofs.testAuthentication().then((result) => {
    //handle successful authentication here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

Usage

Once you've set up your instance, using the ethoFS SDK is easy. Simply call your desired function and handle the results of the promise.

Authentication Not Required (ethoFS key not required on initialization)

• Data
  • networkStats
  • nodeLocations
  • calculateCost

Authentication Required (ethoFS key required on initialization)

• User

  • addUser

• Pinning

  • pinFileToIPFS
  • pinFolderToIPFS
  • pinFromFS
  • extendPin
  • unpin

• Data

  • testAuthentication
  • pinList

### `networkStats` Retrieve ethoFS Network Stats.

ethofs.networkStats()

Params

Response

{
    activeUploadContracts: This is number of active upload contracts on the network,
    totalNetworkStorageUse: This is total used storage space(in bytes) used on the network,
    networkStorageAvailable: This is total used storage space(in bytes) available on the network,
    active_gatewaynodes: This is total number of active Gateway Nodes on the network,
    active_masternodes: This is total number of active Masternodes on the network,
    active_servicenodes: This is total number of active Service Nodes on the network,
    gatewaynode_reward: This is the previous daily reward payment for Gateway Nodes,
    masternode_reward: This is the previous daily reward payment for Masternodes,
    servicenode_reward: This is the previous daily reward payment for Service Nodes
}

Example Code

ethofs.networkStats().then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

nodeLocations

Retrieve ethoFS Node Location Information.

ethofs.nodeLocations()

Params

Response Array

[
    {
        type: This is type of node (Gateway Node, Masternode, Service Node),
        country: This is the country where node is located in,
        city: This is the city where node is located in,
        latitude: This is the latitude of node (geolocated by IP address),
        longitude: This is the longitude of node (geolocated by IP address)
    }
]

Example Code

ethofs.nodeLocations().then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

calculateCost

Estimate cost of a data upload by sending a request with upload duration and estimated size.

ethofs.calculateCost(options)

Params

• readableStream - A readableStream of the file to be added
• options : A JSON object that contains the following keyvalues:
  • ethofsOptions : A JSON object with additional options for the data being pinned

Response

{
    uploadSize: This is the calculated size of the upload,
    uploadDuration: This is the upload contract duration provided by the user,
    uploadCost: This is the calculated total cost in ETHO (wei) for the upload
}

Example Code

const fs = require('fs');
const readableStreamForFile = fs.createReadStream('./yourfile.png');
const options = {
    ethofsOptions: {
        hostingContractDuration: 100000,
        hostingContractSize: 20000000
    }
};
ethofs.calculateCost(options).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

addUser

Add a new user/address to ethoFS network.

ethofs.addUser(userName)

Params

• userName - A string of the desired user name for ethoFS registration

Response

{
    ethoTXHash: This is transaction hash of the confirmed upload contract on the Ether-1 Network
}

Example Code

var userName = 'TestUserName';

ethofs.addUser(userName).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

pinFileToIPFS

Send a file to ethoFS for direct pinning to IPFS.

ethofs.pinFileToIPFS(readableStream, options)

Params

• readableStream - A readableStream of the file to be added
• options : A JSON object that contains the following keyvalues:
  • ethofsData : A JSON object with (#ethofsData-anchor) for the data being pinned
  • ethofsOptions : A JSON object with additional options for the data being pinned

Response

{
    ipfsHash: This is the IPFS multi-hash provided back for your content,
    ethoTXHash: This is transaction hash of the confirmed upload contract on the Ether-1 Network,
    uploadCost: This is the total cost in ETHO for the upload,
    initiationBlock: This is the block number the upload contract was initialized/created on,
    expirationBlock: This is the block number that the upload contract will expire on
}

Example Code

const fs = require('fs');
const readableStreamForFile = fs.createReadStream('./yourfile.png');
const options = {
    ethofsData: {
        name: 'MyCustomUploadName',
        keyvalues: {
            customKey: 'customValue',
            customKey2: 'customValue2'
        }
    },
    ethofsOptions: {
        hostingContractDuration: 100000
    }
};
ethofs.pinFileToIPFS(readableStreamForFile, options).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

pinFolderToIPFS

Send a folder to ethoFS for direct pinning to IPFS.

ethofs.pinFolderToIPFS(readableStream, options)

Params

• readableStream - A readableStream of the folder to be added
• options : A JSON object that contains the following keyvalues:
  • ethofsData : A JSON object with (#ethofsData-anchor) for the data being pinned
  • ethofsOptions : A JSON object with additional options for the data being pinned

Response

{
    ipfsHash: This is the IPFS multi-hash provided back for your content,
    ethoTXHash: This is transaction hash of the confirmed upload contract on the Ether-1 Network,
    uploadCost: This is the total cost in ETHO for the upload,
    initiationBlock: This is the block number the upload contract was initialized/created on,
    expirationBlock: This is the block number that the upload contract will expire on
}

Example Code

const fs = require('fs');
const readableStreamForFolder = fs.createReadStream('./yourDirectory');
const options = {
    ethofsData: {
        name: 'MyCustomUploadName',
        keyvalues: {
            customKey: 'customValue',
            customKey2: 'customValue2'
        }
    },
    ethofsOptions: {
        hostingContractDuration: 100000
    }
};
ethofs.pinFolderToIPFS(readableStreamForFolder, options).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

pinFromFS

Send a file/directory from local filesystem to ethoFS for direct pinning to IPFS.

ethofs.pinFromFS(fsLocation, options)

Params

• fsLocation - A local filesystem location of the file or directory to be added
• options : A JSON object that contains the following keyvalues:
  • ethofsData : A JSON object with (#ethofsData-anchor) for the data being pinned
  • ethofsOptions : A JSON object with additional options for the data being pinned

Response

{
    ipfsHash: This is the IPFS multi-hash provided back for your content,
    ethoTXHash: This is transaction hash of the confirmed upload contract on the Ether-1 Network,
    uploadCost: This is the total cost in ETHO for the upload,
    initiationBlock: This is the block number the upload contract was initialized/created on,
    expirationBlock: This is the block number that the upload contract will expire on
}

Example Code

const sourceDirectory = ('./yourDirectory');
const options = {
    ethofsData: {
        name: 'MyCustomDirectoryUploadName',
        keyvalues: {
            customKey: 'customValue',
            customKey2: 'customValue2'
        }
    },
    ethofsOptions: {
        hostingContractDuration: 100000
    }
};
ethofs.pinFromFS(sourceDirectory, options).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

extendPin

Have ethoFS extend the contract by increasing the expiration blocktime of content that you've pinned/uploaded through the platform.

ethofs.extendPin(uploadContractAddress, options)

Params

• uploadContractAddress - the upload contract address of the content you wish to extend with ethoFS
• options : A JSON object that contains the following keyvalues:
  • ethofsOptions : A JSON object with (#ethofsOptions-anchor) for the data being extended

Response

{
    ethoTXHash: This is transaction hash of the confirmed upload contract extension on the Ether-1 Network
}

Example Code

const options = {
    ethofsOptions: {
        hostingContractDuration: 100000
    }
};
ethofs.extendPin(hostingContractAddress, options).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

unpin

Have ethoFS unpin content that you've pinned/uploaded through the platform.

ethofs.unpin(uploadContractAddress)

Params

• uploadContractAddress - the upload contract address of the content you wish to remove from ethoFS

Response

{
    ethoTXHash: This is transaction hash of the confirmed upload contract removal on the Ether-1 Network
}

Example Code

ethofs.unpin(hashToUnpin).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

testAuthentication

Tests that you can authenticate with ethoFS correctly and the authentication key is registered

ethofs.testAuthentication()

Params

None

Response

{
    authenticated: true
}

Example Code

ethofs.testAuthentication().then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

pinList

List pin contracts stored in ethoFS.

ethofs.pinList(options)

Params

• options (optional) : A JSON object that contains the following keyvalues:
  • ethofsDataFilter (optional) : A JSON object with (#ethofsDataFilter-anchor) for the filtering out pinned data

Response

{
    address: This is the Ether-1 contract address,
    data: This is any saved data along with upload (ie name/keyvalues),
    ipfsHash: This is the IPFS multi-hash provided back for your content,
    initiationBlock: This is the original Ether-1 block the upload was iniated/recorded in,
    expirationBlock: This is the Ether-1 expiration block of the upload contract
}

Example Code

const options = {
    ethofsDataFilter: {
        name: 'MyNameFilter',
        keyvalues: {
            customKeyFilter: 'customValueFilter',
            customKey2Filter: 'customValue2Filter'
        }
    },
};
ethofs.pinList(options).then((result) => {
    //handle results here
    console.log(result);
}).catch((err) => {
    //handle error here
    console.log(err);
});

ethoFS Options

Some endpoints allow you to pass additional options for ethoFS to take into account when adding content to IPFS.

The options object can consist of the following values:

• uploadContractDuration (required) - The duration in ETHO blocks you would like your upload pinned for. A minimum of 100000 blocks is required.

Example ethofsOptions object

{
    hostingContractDuration: 100000
}

ethoFS Data

Some endpoints allow you to pass additional data to store with your IPFS upload.

The options object can consist of the following values:

• name (optional) - The name of your upload.
• keyvalues (optional) - Misc metadata to store with your upload.

Example ethofsData object

{
    name: 'UploadContractName',
    keyvalues: {
        customKey: 'customValue',
        customKey2: 'customValue2'
    }
}

ethoFS Data Filter

Some endpoints allow you to pass additional data filters to filter out existing contracts.

The options object can consist of the following values:

• name (optional) - The name of your upload.
• keyvalues (optional) - Misc metadata stored with your upload.

Example ethofsDataFilter object

{
    name: 'UploadContractNameFilter',
    keyvalues: {
        customKeyFilter: 'customValueFilter',
        customKey2Filter: 'customValue2Filter'
    }
}

Questions? Issues? Suggestions?

Feel free to file a github issue or email us at [email protected]

We'd love to hear from you!