evernode-js-client 0.4.53 → 0.5.1

package/README.md

@@ -0,0 +1,4 @@
+# Evernode library for nodejs and browser.
+Evernode library contains helper methods to interact with Evernode ecosystem.
+
+- [Source code](https://github.com/HotPocketDev/evernode-js-client)

package/index.js

@@ -11746,18 +11746,37 @@ class BaseEvernodeClient {
 
     }
 
+    /**
+     * Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'.
+     * @param {string} event Event name.
+     * @param {function(event)} handler Callback function to handle the event.
+     */
     on(event, handler) {
         this.events.on(event, handler);
     }
 
+    /**
+    * Listens to the subscribed events. This will listen only once and detach the handler.
+    * @param {string} event Event name.
+    * @param {function(event)} handler Callback function to handle the event.
+    */
     once(event, handler) {
         this.events.once(event, handler);
     }
 
+    /**
+     * Detach the listener event.
+     * @param {string} event Event name.
+     * @param {function(event)} handler (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified.
+     */
     off(event, handler = null) {
         this.events.off(event, handler);
     }
 
+    /**
+     * Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this.
+     * @returns boolean value, 'true' if success.
+     */
     async connect() {
         if (this.connected)
             return true;
@@ -11777,6 +11796,9 @@ class BaseEvernodeClient {
         return true;
     }
 
+    /**
+     * Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this.
+     */
     async disconnect() {
         await this.unsubscribe();
 
@@ -11784,14 +11806,24 @@ class BaseEvernodeClient {
             await this.xrplApi.disconnect();
     }
 
+    /**
+     * Subscribes to the registry client events.
+     */
     async subscribe() {
         await this.xrplAcc.subscribe();
     }
 
+    /**
+     * Unsubscribes from the registry client events.
+     */
     async unsubscribe() {
         await this.xrplAcc.unsubscribe();
     }
 
+    /**
+     * Get the EVR balance in the registry account.
+     * @returns The available EVR amount as a 'string'.
+     */
     async getEVRBalance() {
         const lines = await this.xrplAcc.getTrustLines(EvernodeConstants.EVR, this.config.evrIssuerAddress);
         if (lines.length > 0)
@@ -11800,6 +11832,10 @@ class BaseEvernodeClient {
             return '0';
     }
 
+    /**
+     * Get all XRPL hook states in the registry account.
+     * @returns The list of hook states including Evernode configuration and hosts.
+     */
     async getHookStates() {
         const regAcc = new XrplAccount(this.registryAddress, null, { xrplApi: this.xrplApi });
         const configs = await regAcc.getNamespaceEntries(EvernodeConstants.HOOK_NAMESPACE);
@@ -11809,6 +11845,11 @@ class BaseEvernodeClient {
         return [];
     }
 
+    /**
+     * Get the moment from the given XRP ledger index. (1 Moment - 1190 XRP ledgers).
+     * @param {number} ledgerIndex [Optional] Ledger index to get the moment value.
+     * @returns The moment of the given XPR ledger index as 'number'. Returns current moment if XRP ledger index is not given.
+     */
     async getMoment(ledgerIndex = null) {
         const lv = ledgerIndex || this.xrplApi.ledgerIndex;
         const m = Math.floor((lv - this.config.momentBaseIdx) / this.config.momentSize);
@@ -11817,6 +11858,11 @@ class BaseEvernodeClient {
         return m;
     }
 
+    /**
+     * Get start XRP ledger index of the moment (of the given XRPL index).
+     * @param {number} ledgerIndex [Optional] Ledger index to get the moment value.
+     * @returns The XRP ledger index of the moment (of the given XRPL index) as a 'number'. Returns the current moment's start XRP ledger index if ledger index parameter is not given.
+     */
     async getMomentStartIndex(ledgerIndex = null) {
         const lv = ledgerIndex || this.xrplApi.ledgerIndex;
         const m = Math.floor((lv - this.config.momentBaseIdx) / this.config.momentSize);
@@ -11825,6 +11871,10 @@ class BaseEvernodeClient {
         return this.config.momentBaseIdx + (m * this.config.momentSize);
     }
 
+    /**
+     * Get Evernode configuration
+     * @returns An object with all the configuration and their values.
+     */
     async #getEvernodeConfig() {
         let states = await this.getHookStates();
         const configStateKeys = {
@@ -11850,10 +11900,18 @@ class BaseEvernodeClient {
         return config;
     }
 
+    /**
+     * Loads the configs from XRPL hook and updates the in-memory config.
+     */
     async refreshConfig() {
         this.config = await this.#getEvernodeConfig();
     }
 
+    /**
+     * Extracts transaction info and emits the Evernode event.
+     * @param {object} tx XRPL transaction to be handled.
+     * @param {any} error Error if there's any.
+     */
     async #handleEvernodeEvent(tx, error) {
         if (error)
             console.error(error);
@@ -11866,6 +11924,11 @@ class BaseEvernodeClient {
         }
     }
 
+    /**
+     * Extracts the transaction info from a given transaction.
+     * @param {object} tx Transaction to be deserialized and extracted.
+     * @returns The event object in the format {name: '', data: {}}. Returns null if not handled. Note: You need to deserialize memos before passing the transaction to this function.
+     */
     async extractEvernodeEvent(tx) {
         if (tx.TransactionType === 'NFTokenAcceptOffer' && tx.NFTokenSellOffer && tx.Memos.length >= 1 &&
             tx.Memos[0].type === MemoTypes.ACQUIRE_LEASE && tx.Memos[0].format === MemoFormats.BASE64 && tx.Memos[0].data) {
@@ -12082,7 +12145,11 @@ class BaseEvernodeClient {
         return null;
     }
 
-    // To get Host details from Hook States.
+    /**
+     * Get the registered host information.
+     * @param {string} hostAddress [Optional] Address of the host.
+     * @returns The registered host information object. Returns null is not registered.
+     */
     async getHostInfo(hostAddress = this.xrplAcc.address) {
         try {
             const addrStateKey = StateHelpers.generateHostAddrStateKey(hostAddress);
@@ -12108,7 +12175,7 @@ class BaseEvernodeClient {
             }
         }
         catch (e) {
-            // If the exeption is entryNotFound from Rippled there's no entry for the host, So return null.
+            // If the exception is entryNotFound from Rippled there's no entry for the host, So return null.
             if (e?.data?.error !== 'entryNotFound')
                 throw e;
         }
@@ -12116,7 +12183,13 @@ class BaseEvernodeClient {
         return null;
     }
 
-    // To fetch records from host collection in Firestore database. (Pagination is applied - default page size :20)
+    /**
+     * Get all the hosts registered in Evernode. The result's are paginated. Default page size is 20. Note: Specifying both filter and pagination does not supported.
+     * @param {object} filters [Optional] Filter criteria to filter the hosts. The filter key can be a either property of the host.
+     * @param {number} pageSize [Optional] Page size for the results.
+     * @param {string} nextPageToken [Optional] Next page's token, If received by the previous result set.
+     * @returns The list of active hosts. The response will be in '{data: [], nextPageToken: ''}' only if there are more pages. Otherwise the response will only contain the host list. 
+     */
     async getHosts(filters = null, pageSize = null, nextPageToken = null) {
         const hosts = await this.#firestoreHandler.getHosts(filters, pageSize, nextPageToken);
         const curMomentStartIdx = await this.getMomentStartIndex();
@@ -12129,7 +12202,10 @@ class BaseEvernodeClient {
         return hosts;
     }
 
-    // To fetch all records from config collection in Firestore database.
+    /**
+     * Get all Evernode configuration without paginating.
+     * @returns The list of configuration.
+     */
     async getAllConfigs() {
         let fullConfigList = [];
         const configs = await this.#firestoreHandler.getConfigs();
@@ -12149,7 +12225,10 @@ class BaseEvernodeClient {
         return fullConfigList;
     }
 
-    // To fetch all records from host collection in Firestore database.
+    /**
+     * Get all the hosts without paginating.
+     * @returns The list of hosts.
+     */
     async getAllHosts() {
         let fullHostList = [];
         const hosts = await this.#firestoreHandler.getHosts();
@@ -12169,7 +12248,10 @@ class BaseEvernodeClient {
         return fullHostList;
     }
 
-    // To prune an inactive host/
+    /**
+     * Remove a host which is inactive for a long period. The inactivity is checked by Evernode it self and only pruned if inactive thresholds are met.
+     * @param {string} hostAddress XRPL address of the host to be pruned.
+     */
     async pruneDeadHost(hostAddress) {
         if (this.xrplAcc.address === this.registryAddress)
             throw 'Invalid function call';
@@ -12190,6 +12272,7 @@ module.exports = {
     BaseEvernodeClient
 }
 
+
 /***/ }),
 
 /***/ 1437:
@@ -12574,10 +12657,18 @@ const RegistryEvents = {
 
 class RegistryClient extends BaseEvernodeClient {
 
+    /**
+     * Constructs a registry client instance.
+     * @param {object} options [Optional] An object with 'rippledServer' URL and 'registryAddress'.
+     */
     constructor(options = {}) {
         super((options.registryAddress || DefaultValues.registryAddress), null, Object.values(RegistryEvents), false, options);
     }
 
+    /**
+     * Gets all the active hosts registered in Evernode without paginating.
+     * @returns The list of active hosts.
+     */
     async getActiveHosts() {
         let fullHostList = [];
         const hosts = await this.getHosts();
@@ -12629,6 +12720,12 @@ const TenantEvents = {
 
 class TenantClient extends BaseEvernodeClient {
 
+    /**
+     * Constructs a tenant client instance.
+     * @param {string} xrpAddress XRPL address of the tenant.
+     * @param {string} XRPL secret of the tenant.
+     * @param {object} options [Optional] An object with 'rippledServer' URL and 'registryAddress'.
+     */
     constructor(xrpAddress, xrpSecret, options = {}) {
         super(xrpAddress, xrpSecret, Object.values(TenantEvents), false, options);
     }
@@ -12666,6 +12763,13 @@ class TenantClient extends BaseEvernodeClient {
         return host;
     }
 
+    /**
+     * 
+     * @param {string} hostAddress XRPL address of the host to acquire the lease.
+     * @param {object} requirement The instance requirements and configuration.
+     * @param {object} options [Optional] Options for the XRPL transaction.
+     * @returns The transaction result.
+     */
     async acquireLeaseSubmit(hostAddress, requirement, options = {}) {
 
         const hostAcc = await this.getLeaseHost(hostAddress);
@@ -12693,6 +12797,12 @@ class TenantClient extends BaseEvernodeClient {
         return this.xrplAcc.buyNft(selectedOfferIndex, [{ type: MemoTypes.ACQUIRE_LEASE, format: MemoFormats.BASE64, data: ecrypted }], options.transactionOptions);
     }
 
+    /**
+     * Watch for the acquire-success response after the acquire request is made.
+     * @param {object} tx The transaction returned by the acquireLeaseSubmit function.
+     * @param {object} options [Optional] Options for the XRPL transaction.
+     * @returns An object including transaction details,instance info, and acquireReference Id.
+     */
     async watchAcquireResponse(tx, options = {}) {
             console.log(`Waiting for acquire response... (txHash: ${tx.id})`);
 
@@ -12731,6 +12841,13 @@ class TenantClient extends BaseEvernodeClient {
             }
     }
 
+    /**
+     * Acquire an instance from a host
+     * @param {string} hostAddress XRPL address of the host to acquire the lease.
+     * @param {object} requirement The instance requirements and configuration.
+     * @param {object} options [Optional] Options for the XRPL transaction.
+     * @returns An object including transaction details,instance info, and acquireReference Id.
+     */
     acquireLease(hostAddress, requirement, options = {}) {
         return new Promise(async (resolve, reject) => {
             const tx = await this.acquireLeaseSubmit(hostAddress, requirement, options).catch(error => {
@@ -12747,13 +12864,27 @@ class TenantClient extends BaseEvernodeClient {
         });
     }
 
+    /**
+     * This function is called by a tenant client to submit the extend lease transaction in certain host. This function will be called inside extendLease function. This function can take four parameters as follows.
+     * @param {string} hostAddress XRPL account address of the host.
+     * @param {number} amount Cost for the extended moments , in EVRs.
+     * @param {string} tokenID Tenant received instance name. this name can be retrieve by performing acquire Lease.
+     * @param {object} options This is an optional field and contains necessary details for the transactions.
+     * @returns The transaction result.
+     */
     async extendLeaseSubmit(hostAddress, amount, tokenID, options = {}) {
         const host = await this.getLeaseHost(hostAddress);
         return this.xrplAcc.makePayment(host.address, amount.toString(), EvernodeConstants.EVR, this.config.evrIssuerAddress,
             [{ type: MemoTypes.EXTEND_LEASE, format: MemoFormats.HEX, data: tokenID }], options.transactionOptions);
     }
 
-    async watchExtendResponse(tx, minLedgerIndex, options = {}) {
+    /**
+     * This function watches for an extendlease-success response(transaction) and returns the response or throws the error response on extendlease-error response from the host XRPL account. This function is called within the extendLease function.
+     * @param {object} tx Response of extendLeaseSubmit.
+     * @param {object} options This is an optional field and contains necessary details for the transactions.
+     * @returns An object including transaction details.
+     */
+    async watchExtendResponse(tx, options = {}) {
         console.log(`Waiting for extend lease response... (txHash: ${tx.id})`);
 
         const failTimeout = setTimeout(() => {
@@ -12762,7 +12893,7 @@ class TenantClient extends BaseEvernodeClient {
 
         let relevantTx = null;
         while (!relevantTx) {
-            const txList = await this.xrplAcc.getAccountTrx(minLedgerIndex);
+            const txList = await this.xrplAcc.getAccountTrx(tx.details.ledger_index);
             for (let t of txList) {
                 t.tx.Memos = TransactionHelper.deserializeMemos(t.tx.Memos);
                 const res = await this.extractEvernodeEvent(t.tx);
@@ -12790,6 +12921,14 @@ class TenantClient extends BaseEvernodeClient {
         }
     }
 
+    /**
+     * This function is called by a tenant client to extend an available instance in certain host. This function can take four parameters as follows.
+     * @param {string} hostAddress XRPL account address of the host.
+     * @param {number} moments 1190 ledgers (est. 1 hour).
+     * @param {string} instanceName Tenant received instance name. this name can be retrieve by performing acquire Lease.
+     * @param {object} options This is an optional field and contains necessary details for the transactions.
+     * @returns An object including transaction details.
+     */
     extendLease(hostAddress, moments, instanceName, options = {}) {
         return new Promise(async (resolve, reject) => {
             const tokenID = instanceName;

package/package.json

@@ -1,6 +1,12 @@
 {
     "name": "evernode-js-client",
-    "version": "0.4.53",
+    "description": "Javascript client library for Evernode.",
+    "keywords": [
+        "Evernode"
+    ],
+    "homepage": "https://github.com/HotPocketDev/evernode-js-client",
+    "license": "MIT",
+    "version": "0.5.1",
     "dependencies": {
         "elliptic": "6.5.4",
         "ripple-address-codec": "4.2.0",