API docs updates

src/clients/base-evernode-client.js

@@ -105,6 +105,7 @@ class BaseEvernodeClient {
     /**
      * Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this.
      * @returns Boolean value `true` if the connection is successful.
+     * @example const status = await client.connect();
      */
     async connect(options = {}) {
         if (this.connected)
@@ -129,6 +130,7 @@ class BaseEvernodeClient {
 
     /**
      * Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this.
+     * @example await client.disconnect();
      */
     async disconnect() {
         await this.unsubscribe();

src/clients/foundation-client.js

@@ -13,6 +13,9 @@ const REPUTATION_HOST_ADDRESS_PARAM_OFFSET = 0;
 const REPUTATION_VALUE_PARAM_OFFSET = 20;
 const REPUTATION_PARAM_SIZE = 21;
 
+/**
+ * Foundation Events
+ */
 const FoundationEvents = {}
 
 /**

src/clients/hook-clients/governor-client.js

@@ -2,6 +2,20 @@ const { BaseEvernodeClient } = require("../base-evernode-client");
 const { Defaults } = require("../../defaults");
 const { EvernodeEvents } = require('../../evernode-common');
 
+/**
+ * Following governor-specific events can be subscribed from Evernode client instances.
+ * @property {string} Initialized - Triggered when governor receives a hook initialization.
+ * @property {string} CandidateProposed - Triggered when governor receives a new candidate proposal.
+ * @property {string} CandidateWithdrawn - Triggered when candidate withdrawal is requested.
+ * @property {string} ChildHookUpdated - Triggered when registry or heartbeat hook is updated.
+ * @property {string} GovernanceModeChanged - Triggered when governor receives a request to change the governance mode.
+ * @property {string} DudHostReported - Triggered when dud host is reported.
+ * @property {string} DudHostRemoved - Triggered when dud host is removed.
+ * @property {string} DudHostStatusChanged - Triggered when dud host candidate election status is changed.
+ * @property {string} FallbackToPiloted - Triggered when governance mode is changed to piloted mode.
+ * @property {string} NewHookStatusChanged - Triggered when new hook candidate election status is changed.
+ * @property {string} LinkedDudHostCandidateRemoved - Triggered when a host related to dud host candidate is removed by de-registration/transfer or prune.
+ */
 const GovernorEvents = {
     Initialized: EvernodeEvents.Initialized,
     CandidateProposed: EvernodeEvents.CandidateProposed,
@@ -19,10 +33,19 @@ const GovernorEvents = {
 /**
  * GovernorClient is responsible for managing governor operations in Evernode.
  * It interacts with the XRP Ledger using the governor address and listens for specific governor events.
- * 
  * @extends BaseEvernodeClient
  */
 class GovernorClient extends BaseEvernodeClient {
+    /**
+     * Creates an instance of GovernorClient.
+     * @param {Object} [options={}] - A JSON object of options for initializing the GovernorClient.
+     * @param {string} [options.governorAddress] - (Optional) The Governor Hook Account Xahau address. 
+     * If not provided, the address from the 'Defaults' configuration will be used.
+     * @example
+     * const governorClient = new GovernorClient({
+     *     governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL"
+     * });
+     */
     constructor(options = {}) {
         super((options.governorAddress || Defaults.values.governorAddress), null, Object.values(GovernorEvents), false, options);
     }

src/clients/hook-clients/heartbeat-client.js

@@ -1,6 +1,11 @@
 const { BaseEvernodeClient } = require("../base-evernode-client");
 const { EvernodeEvents } = require('../../evernode-common');
 
+/**
+ * Following heartbeat-specific events can be subscribed from Evernode client instances.
+ * @property {string} Heartbeat - Triggered when a heartbeat from a host is received.
+ * @property {string} FoundationVoted - Triggered when foundation vote for a candidate is received.
+ */
 const HeartbeatEvents = {
     Heartbeat: EvernodeEvents.Heartbeat,
     FoundationVoted: EvernodeEvents.FoundationVoted
@@ -9,10 +14,20 @@ const HeartbeatEvents = {
 /**
  * HeartbeatClient is responsible for managing heartbeat operations in Evernode.
  * It interacts with the XRP Ledger using the heartbeat address and listens for specific heartbeat events.
- * 
  * @extends BaseEvernodeClient
  */
 class HeartbeatClient extends BaseEvernodeClient {
+    /**
+     * Creates an instance of HeartbeatClient.
+     * @param {Object} [options={}] - A JSON object of options for initializing the HeartbeatClient.
+     * @param {string} options.heartbeatAddress - The Heartbeat Hook Account Xahau address.
+     * @param {string} [options.rippledServer] - (Optional) The Rippled server URL.
+     * @example
+     * const heartbeatClient = new HeartbeatClient({
+     *     heartbeatAddress: 'raPSFU999HcwpyRojdNh2i96T22gY9fgxL',
+     *     rippledServer: 'wss://hooks-testnet-v3.xrpl-labs.com'
+     * });
+     */
     constructor(options = {}) {
         super(options.heartbeatAddress, null, Object.values(HeartbeatEvents), false, options);
     }

src/clients/hook-clients/hook-client-factory.js

@@ -6,15 +6,33 @@ const { ReputationClient } = require("./reputation-client");
 
 /**
  * A factory class for creating different types of hook clients based on the provided hook type.
+ * @summary
+ * In Evernode, there are three distinct types of hooks:
+ * 
+ * - Governor Hook
+ * - Registry Hook
+ * - Heartbeat Hook
+ * - Reputation Hook
+ * 
+ * Each of these hooks is associated with a separate Xahau account. Therefore, in various scenarios, it becomes necessary to create client instances to engage with these hooks.
+ * This section aims to enhance your comprehension of the available hook clients in Evernode. It will provide you with detailed specifications and guidance on how to utilize them effectively within Evernode.
+ * The Hook Client Factory provides a common interface for creating hook clients. Developers can instantiate hook clients with minimal effort.
  * @class
  */
+
 class HookClientFactory {
     /**
      * Creates a hook client from given type.
      * @param {string} hookType Type of the Required Hook. (Supported Hook types 'GOVERNOR', 'REGISTRY', 'HEARTBEAT' and 'REPUTATION')
      * @param {Object} [options={}] - Optional configuration for the hook client.
      * @returns {Promise<Object|null>} - Returns a promise that resolves to an instance of the requested HookClient type, or `null` if the type is unsupported.
      * @throws {Error} Will throw an error if there is an issue connecting to the GovernorClient or obtaining the necessary configuration.
+     * @example
+     * Defaults.set({governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL"});
+     * const governorClient = await HookClientFactory.create(HookTypes.governor);
+     * const registryClient = await HookClientFactory.create(HookTypes.registry);
+     * const heartbeatClient = await HookClientFactory.create(HookTypes.heartbeat);
+     * const reputationClient = await HookClientFactory.create(HookTypes.reputation);
      */
     static async create(hookType, options = {}) {
         let governorClient;

src/clients/hook-clients/registry-client.js

@@ -1,6 +1,16 @@
 const { BaseEvernodeClient } = require("../base-evernode-client");
 const { EvernodeEvents } = require('../../evernode-common');
 
+/**
+ * Following registry-specific events can be subscribed from Evernode client instances.
+ * @property {string} HostRegistered - Triggered when host registration event is received to the registry.
+ * @property {string} HostDeregistered - Triggered when host de-registration event is received to the registry.
+ * @property {string} HostRegUpdated - Triggered when host sends an update info request.
+ * @property {string} DeadHostPrune - Triggered when dead host prune request is received to the registry.
+ * @property {string} HostTransfer - Triggered when host transfer is requested by the host.
+ * @property {string} HostRebate - Triggered when host rebate is requested by the host.
+ * @property {string} HostReputationUpdated - Triggered when host reputation is updated.
+ */
 const RegistryEvents = {
     HostRegistered: EvernodeEvents.HostRegistered,
     HostDeregistered: EvernodeEvents.HostDeregistered,
@@ -14,11 +24,21 @@ const RegistryEvents = {
 /**
  * RegistryClient is responsible for managing registry operations in Evernode.
  * It interacts with the XRP Ledger using the registry address and listens for specific registry events.
- * 
  * @extends BaseEvernodeClient
  */
 class RegistryClient extends BaseEvernodeClient {
 
+    /**
+     * Creates an instance of RegistryClient.
+     * @param {Object} [options={}] - A JSON object of options for initializing the RegistryClient.
+     * @param {string} options.registryAddress - The Registry Hook Account Xahau address.
+     * @param {string} [options.rippledServer] - (Optional) The Rippled server URL.
+     * @example
+     * const registryClient = new RegistryClient({
+     *     registryAddress: 'rQUhXd7sopuga3taru3jfvc1BgVbscrb1X',
+     *     rippledServer: 'wss://hooks-testnet-v3.xrpl-labs.com'
+     * });
+     */
     constructor(options = {}) {
         super(options.registryAddress, null, Object.values(RegistryEvents), false, options);
     }

src/clients/hook-clients/reputation-client.js

@@ -6,11 +6,19 @@ const ReputationEvents = {}
 /**
  * ReputationClient is responsible for managing reputation operations in Evernode.
  * It interacts with the XRP Ledger using the reputation address and listens for specific reputation events.
- * 
  * @extends BaseEvernodeClient
  */
 class ReputationClient extends BaseEvernodeClient {
 
+    /**
+     * Creates an instance of ReputationClient.
+     * @param {Object} [options={}] - A JSON object of options for initializing the ReputationClient.
+     * @param {string} options.reputationAddress - The Reputation Hook Account Xahau address.
+     * @example
+     * const reputationClient = new reputationAddress({
+     *     reputationAddress: 'rQUhXd7sopuga3taru3jfvc1BgVbscrb1X',
+     * });
+     */
     constructor(options = {}) {
         super(options.reputationAddress, null, Object.values(ReputationEvents), false, options);
     }

src/clients/host-client.js

@@ -15,6 +15,12 @@ const { UtilHelpers } = require('../util-helpers');
 
 const OFFER_WAIT_TIMEOUT = 60;
 
+/**
+ * Following host-specific events can be subscribed from Evernode client instances.
+ * @property {string} AcquireLease - Triggered when the host receives a lease acquire request.
+ * @property {string} ExtendLease - Triggered when the host receives a lease extend request.
+ * @property {string} TerminateLease - Triggered when the host receives a lease termination request.
+ */
 const HostEvents = {
     AcquireLease: EvernodeEvents.AcquireLease,
     ExtendLease: EvernodeEvents.ExtendLease,
@@ -73,7 +79,6 @@ class HostClient extends BaseEvernodeClient {
 
     /**
      * Creates an instance of HostClient.
-     * 
      * @param {string} xrpAddress - The XRP address to associate with this client.
      * @param {string} xrpSecret - The secret (private key) associated with the XRP address.
      * @param {Object} [options={}] - Additional configuration options for the HostClient.
@@ -88,6 +93,11 @@ class HostClient extends BaseEvernodeClient {
         return res;
     }
 
+    /**
+     * Set reputation account detatils.
+     * @param {string} [reputationAddress = null] - XRPL address of the reputation account.
+     * @param {string} [reputationSecret = null] - XRPL secret of the reputation account.
+     */
     async setReputationAcc(reputationAddress = null, reputationSecret = null) {
         let hostReputationAccId;
         if (!reputationAddress && !reputationSecret) {
@@ -138,7 +148,7 @@ class HostClient extends BaseEvernodeClient {
 
     /**
      * Get lease token by index.
-     * @param index Index of the token.
+     * @param {string}index Index of the token.
      * @returns Lease token.
      */
     async getLeaseByIndex(index) {

src/clients/tenant-client.js

@@ -10,6 +10,13 @@ const { XrplConstants } = require('../xrpl-common');
 
 const DEFAULT_WAIT_TIMEOUT = 300000;
 
+/**
+ * Following tenant-specific events can be subscribed from Evernode client instances.
+ * @property {string} AcquireSuccess - Triggered when the tenant receives an acquire success response.
+ * @property {string} AcquireError - Triggered when the tenant receives an acquire error response.
+ * @property {string} ExtendSuccess - Triggered when the tenant receives an extend success response.
+ * @property {string} ExtendError - Triggered when the tenant receives an extend error response.
+ */
 const TenantEvents = {
     AcquireSuccess: EvernodeEvents.AcquireSuccess,
     AcquireError: EvernodeEvents.AcquireError,
@@ -26,9 +33,16 @@ class TenantClient extends BaseEvernodeClient {
 
     /**
      * Creates an instance of TenantClient.
-     * @param {string} xrpAddress - The XRP address to associate with this client.
-     * @param {string} xrpSecret - The secret (private key) associated with the XRP address.
-     * @param {Object} [options={}] - Additional configuration options for the TenantClient.
+     * @param {string} xrpAddress - Xahau wallet address of the tenant.
+     * @param {string} xrpSecret - Secret key of the tenant's Xahau wallet.
+     * @param {Object} [options={}] - (Optional) A JSON object of options that can include the following properties.
+     * @param {string} [options.governorAddress] - (Optional) The Governor Hook Account Xahau address.
+     * @param {string} [options.rippledServer] - (Optional) The Rippled server URL.
+     * @example
+     * const client = new TenantClient("rKfHBc8e1VemZPLZoPXB7HjSKU2QjkRfP", "sszyYJ79AdUUF6dR7QfD9ARWfVuz3", {
+     *     governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL",
+     *     rippledServer: "wss://hooks-testnet-v3.xrpl-labs.com"
+     * });
      */
     constructor(xrpAddress, xrpSecret, options = {}) {
         super(xrpAddress, xrpSecret, Object.values(TenantEvents), false, options);
@@ -219,11 +233,65 @@ 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.
+     * Acquires an available instance on a specified host.
+     * @async
+     * @param {string} hostAddress - The wallet address of the host where the HotPocket instance will be created.
+     * @param {Object} requirement - The details necessary for creating the instance.
+     * @param {string} requirement.owner_pubkey - The public key of the tenant.
+     * @param {string} requirement.contract_id - The unique contract identifier.
+     * @param {string} requirement.image - The image used to create the HotPocket instance.
+     * @param {Object} requirement.config - Configuration object for the instance.
+     * @param {Object} [options={}] - Optional configurations for the transaction.
+     * @param {number} [options.timeout=60000] - Timeout for the transaction in milliseconds.
+     * @param {string} [options.leaseOfferIndex] - The index of the preferred lease offer from the host.
+     * @param {Object} [options.transactionOptions] - Options for the URITokenBuy transaction as defined in the Xahau documentation.
+     * @returns {Promise<Object>} Resolves with an object containing the transaction details and instance details.
+     * @returns {Object} transaction - Information about the transaction.
+     * @returns {string} transaction.Account - The address of the account initiating the transaction.
+     * @returns {string} transaction.Amount - The amount of currency transferred.
+     * @returns {string} transaction.Destination - The tenant's account address.
+     * @returns {string} transaction.Fee - The fee paid for the transaction, in EVR drops.
+     * @returns {number} transaction.LastLedgerSequence - The latest ledger sequence for the transaction.
+     * @returns {Object[]} transaction.Memos - Array of memo objects.
+     * @returns {string} transaction.hash - The SHA-512 hash of the transaction.
+     * @returns {number} transaction.ledger_index - The ledger index containing the transaction.
+     * @returns {string} transaction.DeliveredAmount - The actual amount delivered to the destination.
+     * @returns {Object} instance - Information about the acquired instance.
+     * @returns {string} instance.name - The unique identifier (URITokenID) of the instance.
+     * @returns {string} instance.pubkey - The public key of the instance.
+     * @returns {string} instance.contract_id - The unique contract identifier.
+     * @returns {string} instance.peer_port - The port used for peer communication.
+     * @returns {string} instance.user_port - The port used for user communication.
+     * @returns {string} instance.domain - The public domain of the host server.
+     * @returns {string} acquireRefId - The reference ID for the acquisition.
+     * @throws {Error} Throws an error if the acquisition fails.
+     * @throws {Object} error - The error object with details about the failure.
+     * @throws {string} error.error - The error code ('ACQUIRE_ERR').
+     * @throws {string} error.reason - The reason for the acquisition failure.
+     * @throws {Object} error.transaction - The transaction details associated with the failed acquisition.
+     * @throws {string} error.transaction.Account - The tenant's account address.
+     * @throws {Object} error.transaction.Amount - The refund details.
+     * @throws {string} error.transaction.Amount.currency - The currency type (e.g., 'EVR').
+     * @throws {string} error.transaction.Amount.issuer - The issuer of the currency.
+     * @throws {string} error.transaction.Amount.value - The value of the refunded amount.
+     * @throws {string} error.transaction.Destination - The tenant's account address.
+     * @throws {string} error.transaction.Fee - The transaction fee.
+     * @throws {Object[]} error.transaction.HookParameters - Contains event name and event data.
+     * @throws {string} error.transaction.HookParameters[].name - The event name (in hex format).
+     * @throws {string} error.transaction.HookParameters[].value - The event data (in hex format).
+     * @throws {string} error.acquireRefId - The reference ID for the failed acquisition request.
+     * @example
+     * const result = await tenant.acquireLease(
+     *   "rnET2YR19WDP4vB8XtDhcF2J4afqMM6xim",
+     *   {
+     *     owner_pubkey: "ed5cb83404120ac759609819591ef839b7d222c84f1f08b3012f490586159d2b50",
+     *     contract_id: "dc411912-bcdd-4f73-af43-32ec45844b9a",
+     *     image: "evernodedev/sashimono:hp.latest-ubt.20.04-njs.16",
+     *     config: {}
+     *   },
+     *   { timeout: 10000 }
+     * );
+     * console.log("Tenant received instance:", result);
      */
     acquireLease(hostAddress, requirement, options = {}) {
         return new Promise(async (resolve, reject) => {

src/defaults.js

@@ -5,6 +5,9 @@ const DefinitionsUrl = 'https://raw.githubusercontent.com/EvernodeXRPL/evernode-
 const DefaultValues = {
     xrplApi: null
 }
+/**
+ * The four Evernode hook types. governor,registry, heartbeat and reputation.
+ */
 
 const HookTypes = {
     governor: 'GOVERNOR',
@@ -51,6 +54,8 @@ class Defaults {
     /**
      * Override Evernode default configs.
      * @param {object} newDefaults Configurations to override `{ governorAddress: '{string} governor xrpl address', rippledServer: '{string} rippled server url', xrplApi: '{XrplApi} xrpl instance', stateIndexId: '{string} firestore index', networkID: '{number} rippled network id' }`
+     * @returns {void}
+     * @example Defaults.set({governorAddress: 'rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL'});
      */
     static set(newDefaults) {
         Object.assign(DefaultValues, newDefaults)
@@ -59,6 +64,7 @@ class Defaults {
     /**
      * Read Evernode default configs.
      * @returns The Object of Evernode configs
+     * @example const defaults = Defaults.values;
      */
     static get values() {
         return { ...DefaultValues };