@ethofs/sdk

    1.0.10 • Public • Published

    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)

    Authentication Required (ethoFS key required on initialization)


    ### `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 unpin 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 remove from 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 admin@ether1.org

    We'd love to hear from you!

    Install

    npm i @ethofs/sdk

    DownloadsWeekly Downloads

    19

    Version

    1.0.10

    License

    MIT

    Unpacked Size

    20.3 MB

    Total Files

    30

    Last publish

    Collaborators

    • dev-jamesr