@ethoprotocol/sdk
v0.0.3
Official SDK for the Etho Protocol Network
0/weekUpdated 3 years agoMITUnpacked: 24.7 MB
Published by ethoprotocol
npm install @ethoprotocol/sdk
Etho Protocol SDK
Official NodeJS SDK for Etho Protocol
Overview
The Etho Protocol NodeJS SDK provides the quickest / easiest path for interacting with the Etho Protocol Network.
Installation
``
npm install --save @ethoprotocol/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
javascript
const ethofsSDK = require('@ethoprotocol/sdk');
const ethofs = ethofsSDK();
`
Initialization With Authentication
javascript
const ethofsSDK = require('@ethoprotocol/sdk');
const ethofs = ethofsSDK('yourETHOPrivateKey');
`
Initialization With Custom RPC/Gateway Locations
##### Params
* : A JSON object that contains the following keyvalues:
* rpc (optional) : The Etho Protocol RPC Location
* gateway (optional) : The IPFS API/Gateway Location
##### Example Code
`javascript
const connections = {
rpc: 'https://rpc.ethoprotocol.com',
gateway: 'https://gateway.ethoprotocol.com'
};
const ethofsSDK = require('@ethoprotocol/sdk');
const ethofs = ethofsSDK('yourETHOPrivateKey', connections);
`Quickly test that you can connect to the API with the following call:
javascript
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
* calculateCostAuthentication Required (ethoFS key required on initialization)
* User
* addUser
* Pinning
* pinFileToIPFS
* pinFolderToIPFS
* pinFromFS
* extendPin
* unpin* Data
* testAuthentication
* pinList
$3
Retrieve ethoFS Network Stats.#####
##### 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
javascript
ethofs.networkStats().then((result) => {
//handle results here
console.log(result);
}).catch((err) => {
//handle error here
console.log(err);
});
`
$3
Retrieve Etho Protocol Node Location Information.#####
##### Params#### Response Array
[
{
type: This is type of node (Gateway Node, Masternode, Service Node),
id: This is the unique node id,
latitude: This is the latitude of node (geolocated by IP address),
longitude: This is the longitude of node (geolocated by IP address)
}
]
##### Example Code
javascript
ethofs.nodeLocations().then((result) => {
//handle results here
console.log(result);
}).catch((err) => {
//handle error here
console.log(err);
});
`
$3
Estimate cost of a data upload by sending a request with upload duration and estimated size.#####
##### Params
* - 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
javascript
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);
});
`
$3
Add a new user/address to ethoFS network.#####
##### Params
* - 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
javascript
var userName = 'TestUserName';ethofs.addUser(userName).then((result) => {
//handle results here
console.log(result);
}).catch((err) => {
//handle error here
console.log(err);
});
`
$3
Send a file to ethoFS for direct pinning to IPFS.#####
##### Params
* - 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
javascript
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);
});
`
$3
Send a folder to ethoFS for direct pinning to IPFS.#####
##### Params
* - 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
javascript
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);
});
`
$3
Send a file/directory from local filesystem to ethoFS for direct pinning to IPFS.#####
##### Params
* - 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
javascript
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);
});
`
$3
Have ethoFS extend content that you've pinned/uploaded through the platform.#####
##### Params
* - 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
javascript
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);
});
`
$3
Have ethoFS unpin content that you've pinned/uploaded through the platform.#####
##### Params
* - 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
javascript
ethofs.unpin(hashToUnpin).then((result) => {
//handle results here
console.log(result);
}).catch((err) => {
//handle error here
console.log(err);
});
`$3
Tests that you can authenticate with ethoFS correctly and the authentication key is registered#####
##### Params
None#### Response
{
authenticated: true
}
##### Example Code
javascript
ethofs.testAuthentication().then((result) => {
//handle results here
console.log(result);
}).catch((err) => {
//handle error here
console.log(err);
});
`
$3
List pin contracts stored in ethoFS.#####
##### Params
* (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
javascript
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@ethoprotocol.com
We'd love to hear from you!