From ccf236f06c828f274d65afa2fe265f3b2ca46b65 Mon Sep 17 00:00:00 2001 From: Dulana Peiris Date: Fri, 20 Sep 2024 02:08:30 +0530 Subject: [PATCH 1/4] Updated API docs --- docs/evernode-js-api.md | 4861 +++++++++++++++++ docs/filelist | 19 + docs/init-docs.js | 44 + package.json | 6 +- src/clients/base-evernode-client.js | 38 +- src/clients/foundation-client.js | 13 + src/clients/hook-clients/governor-client.js | 6 + src/clients/hook-clients/heartbeat-client.js | 6 + .../hook-clients/hook-client-factory.js | 10 +- src/clients/hook-clients/registry-client.js | 10 +- src/clients/hook-clients/reputation-client.js | 6 + src/clients/host-client.js | 13 + src/clients/tenant-client.js | 24 + src/defaults.js | 3 + src/encryption-helper.js | 18 + src/evernode-helpers.js | 53 + src/state-helpers.js | 173 + src/transaction-helper.js | 43 +- src/util-helpers.js | 28 +- src/xfl-helpers.js | 38 +- src/xrpl-account.js | 412 +- src/xrpl-api.js | 184 +- 22 files changed, 5954 insertions(+), 54 deletions(-) create mode 100644 docs/evernode-js-api.md create mode 100644 docs/filelist create mode 100644 docs/init-docs.js diff --git a/docs/evernode-js-api.md b/docs/evernode-js-api.md new file mode 100644 index 0000000..7b76ae9 --- /dev/null +++ b/docs/evernode-js-api.md @@ -0,0 +1,4861 @@ +# Evernode JS API Documentation +## Classes + +
+
BaseEvernodeClient
+

Creates an instance of BaseEvernodeClient.

+
+
FoundationClient ⇐ BaseEvernodeClient
+

FoundationClient class to manage and interact with foundation operations. +It extends the BaseEvernodeClient.

+
+
HeartbeatClient ⇐ BaseEvernodeClient
+

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.

+
+
HookClientFactory
+

A factory class for creating different types of hook clients based on the provided hook type.

+
+
RegistryClient ⇐ BaseEvernodeClient
+

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.

+
+
HostClient ⇐ BaseEvernodeClient
+

HostClient class to manage host operations. +It extends the BaseEvernodeClient.

+
+
TenantClient ⇐ BaseEvernodeClient
+

TenantClient class to manage tenant operations. +It extends the BaseEvernodeClient.

+
+
Defaults
+

Defaults class is responsible for retrieving and overriding the default Evernode network configurations.

+
+
EncryptionHelper
+

EncryptionHelper class is responsible for encrypt and decrypt functions for messages.

+
+
EvernodeHelpers
+

Provides various utility functions for working with leases, tokens, and ledger entries within the Xahau ecosystem.

+
+
StateHelpers
+

Provides various utility functions for working with States.

+
+
TransactionHelper
+

Provides various utility functions for working with Xahau Transactions.

+
+
UtilHelpers
+

Provides utility helper functions for various operations.

+
+
XflHelpers
+

Helper class for handling XFL (Extended Floating-Point) float numbers.

+
+
XrplAccount
+

Represents an XRP Ledger account and provides methods for account management.

+
+
XrplApi
+

Class representing an XRPL API client.

+
+
+ + + +## BaseEvernodeClient +Creates an instance of BaseEvernodeClient. + +**Kind**: global class + +* [BaseEvernodeClient](#BaseEvernodeClient) + * [new BaseEvernodeClient(xrpAddress, xrpSecret, watchEvents, [autoSubscribe], [options])](#new_BaseEvernodeClient_new) + * [.on(event, handler)](#BaseEvernodeClient+on) + * [.once(event, handler)](#BaseEvernodeClient+once) + * [.off(event, handler)](#BaseEvernodeClient+off) + * [.connect()](#BaseEvernodeClient+connect) ⇒ + * [.disconnect()](#BaseEvernodeClient+disconnect) + * [.subscribe()](#BaseEvernodeClient+subscribe) + * [.unsubscribe()](#BaseEvernodeClient+unsubscribe) + * [.getEVRBalance()](#BaseEvernodeClient+getEVRBalance) ⇒ + * [.getHookStates()](#BaseEvernodeClient+getHookStates) ⇒ + * [.getMoment(index)](#BaseEvernodeClient+getMoment) ⇒ + * [.getMomentStartIndex(index)](#BaseEvernodeClient+getMomentStartIndex) ⇒ + * [.refreshConfig()](#BaseEvernodeClient+refreshConfig) + * [.extractEvernodeEvent(tx)](#BaseEvernodeClient+extractEvernodeEvent) ⇒ + * [.getHostInfo(hostAddress)](#BaseEvernodeClient+getHostInfo) ⇒ + * [.getAllHostsFromLedger()](#BaseEvernodeClient+getAllHostsFromLedger) ⇒ + * [.getAllCandidatesFromLedger()](#BaseEvernodeClient+getAllCandidatesFromLedger) ⇒ + * [.pruneDeadHost(hostAddress)](#BaseEvernodeClient+pruneDeadHost) + * [.getCandidateByOwner(ownerAddress)](#BaseEvernodeClient+getCandidateByOwner) ⇒ + * [.getDudHostCandidatesByOwner(ownerAddress)](#BaseEvernodeClient+getDudHostCandidatesByOwner) ⇒ + * [.getCandidateById(candidateId)](#BaseEvernodeClient+getCandidateById) ⇒ + * [.getDudHostVoteInfo(hostAddress)](#BaseEvernodeClient+getDudHostVoteInfo) ⇒ + * [.getPilotedModeVoteInfo()](#BaseEvernodeClient+getPilotedModeVoteInfo) ⇒ + * [.getReputationAddressByOrderedId(orderedId, moment)](#BaseEvernodeClient+getReputationAddressByOrderedId) ⇒ + * [.getReputationOrderByAddress(hostAddress, moment)](#BaseEvernodeClient+getReputationOrderByAddress) ⇒ + * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ + * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + + +### new BaseEvernodeClient(xrpAddress, xrpSecret, watchEvents, [autoSubscribe], [options]) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| xrpAddress | string | | The XRP address associated with the client. | +| xrpSecret | string | | The XRP secret associated with the client. | +| watchEvents | Array.<string> | | An array of event names to watch. | +| [autoSubscribe] | boolean | false | Whether to automatically subscribe to events. | +| [options] | Object | {} | Optional configuration options. | +| [options.governorAddress] | string | | The governor address. Defaults to a predefined value if not provided. | +| [options.xrplApi] | [XrplApi](#XrplApi) | | An instance of XrplApi. If not provided, a new instance will be created. | +| [options.rippledServer] | string | | The URL of the rippled server to use if a new XrplApi instance is created. | +| [options.config] | Object | | Optional configuration settings. | +| [options.messagePrivateKey] | string | | The private key for message encryption, if required. | + + + +### baseEvernodeClient.on(event, handler) +Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| handler | function | The callback function to handle the event. The function takes the event object as a parameter. | + + + +### baseEvernodeClient.once(event, handler) +Listens to the subscribed events. This will listen only once and detach the handler. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | Event name. | +| handler | function | Callback function to handle the event. | + + + +### baseEvernodeClient.off(event, handler) +Detach the listener event. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | Event name. | +| handler | function | | (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified. | + + + +### baseEvernodeClient.connect() ⇒ +Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: Returns `true` if the connection is successful. + + +### baseEvernodeClient.disconnect() +Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + + +### baseEvernodeClient.subscribe() +Subscribes to the client events. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + + +### baseEvernodeClient.unsubscribe() +Unsubscribes from the client events. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + + +### baseEvernodeClient.getEVRBalance() ⇒ +Get the EVR balance in the account. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The available EVR amount as a string. + + +### baseEvernodeClient.getHookStates() ⇒ +Get all XRPL hook states in the registry account. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The list of hook states, including Evernode configuration and hosts. + + +### baseEvernodeClient.getMoment(index) ⇒ +Get the moment from the given index (timestamp). + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment value. | + + + +### baseEvernodeClient.getMomentStartIndex(index) ⇒ +Get start index (timestamp) of the moment. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The index (timestamp) of the moment as a 'number'. Returns the current moment's start index (timestamp) if ledger index parameter is not given. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment start index. | + + + +### baseEvernodeClient.refreshConfig() +Loads the configs from XRPL hook and updates the in-memory config. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + + +### baseEvernodeClient.extractEvernodeEvent(tx) ⇒ +Extracts the transaction info from a given transaction. +Note: You need to deserialize HookParameters before passing the transaction to this function. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction object to be deserialized and extracted. | + + + +### baseEvernodeClient.getHostInfo(hostAddress) ⇒ +Get the registered host information. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The registered host information object. Returns null if not registered. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the host. | + + + +### baseEvernodeClient.getAllHostsFromLedger() ⇒ +Get the hosts registered in Evernode. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The list of hosts. + + +### baseEvernodeClient.getAllCandidatesFromLedger() ⇒ +Get the governor in Evernode. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The list of candidates. + + +### baseEvernodeClient.pruneDeadHost(hostAddress) +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. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to be pruned. | + + + +### baseEvernodeClient.getCandidateByOwner(ownerAddress) ⇒ +Get proposed new hook candidate info. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | [Optional] Address of the owner. | + + + +### baseEvernodeClient.getDudHostCandidatesByOwner(ownerAddress) ⇒ +Get proposed dud host candidates. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: An array of candidate information. Returns empty array if no candidates. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | | Address of the owner | + + + +### baseEvernodeClient.getCandidateById(candidateId) ⇒ +Get candidate info. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate. | + + + +### baseEvernodeClient.getDudHostVoteInfo(hostAddress) ⇒ +Get reported dud host info. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The dud host candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the dud host. | + + + +### baseEvernodeClient.getPilotedModeVoteInfo() ⇒ +Get piloted mode vote info. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: The piloted mode candidate information. Returns null if no candidate. + + +### baseEvernodeClient.getReputationAddressByOrderedId(orderedId, moment) ⇒ +Get reputation order info of given orderedId. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: Reputation address info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| orderedId | number | | Order id of the host. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### baseEvernodeClient.getReputationOrderByAddress(hostAddress, moment) ⇒ +Get reputation order info of given host. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: Reputation order info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | (optional) Host address. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### baseEvernodeClient.getReputationContractInfoByAddress(hostsAddress, moment) ⇒ +Get reputation contract info of given host. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: Reputation contract info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | +| moment | number | (optional) Moment to get reputation contract info for. | + + + +### baseEvernodeClient.getReputationInfoByAddress(hostsAddress) ⇒ +Get reputation info of given host. + +**Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Returns**: Reputation info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | + + + +## FoundationClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) +FoundationClient class to manage and interact with foundation operations. +It extends the BaseEvernodeClient. + +**Kind**: global class +**Extends**: [BaseEvernodeClient](#BaseEvernodeClient) + +* [FoundationClient](#FoundationClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [new FoundationClient(xrpAddress, xrpSecret, [options])](#new_FoundationClient_new) + * [.propose(hashes, shortName, options)](#FoundationClient+propose) ⇒ + * [.withdraw(candidateId, options)](#FoundationClient+withdraw) ⇒ + * [.vote(candidateId, vote, options)](#FoundationClient+vote) ⇒ + * [.reportDudHost(hostAddress, options)](#FoundationClient+reportDudHost) ⇒ + * [.voteDudHost(hostAddress, vote, options)](#FoundationClient+voteDudHost) ⇒ + * [.votePilotedMode(vote, options)](#FoundationClient+votePilotedMode) ⇒ + * [.changeGovernanceMode(mode, options)](#FoundationClient+changeGovernanceMode) ⇒ + * [.updateHostReputation(hostAddress, reputation, options)](#FoundationClient+updateHostReputation) ⇒ + * [.on(event, handler)](#BaseEvernodeClient+on) + * [.once(event, handler)](#BaseEvernodeClient+once) + * [.off(event, handler)](#BaseEvernodeClient+off) + * [.connect()](#BaseEvernodeClient+connect) ⇒ + * [.disconnect()](#BaseEvernodeClient+disconnect) + * [.subscribe()](#BaseEvernodeClient+subscribe) + * [.unsubscribe()](#BaseEvernodeClient+unsubscribe) + * [.getEVRBalance()](#BaseEvernodeClient+getEVRBalance) ⇒ + * [.getHookStates()](#BaseEvernodeClient+getHookStates) ⇒ + * [.getMoment(index)](#BaseEvernodeClient+getMoment) ⇒ + * [.getMomentStartIndex(index)](#BaseEvernodeClient+getMomentStartIndex) ⇒ + * [.refreshConfig()](#BaseEvernodeClient+refreshConfig) + * [.extractEvernodeEvent(tx)](#BaseEvernodeClient+extractEvernodeEvent) ⇒ + * [.getHostInfo(hostAddress)](#BaseEvernodeClient+getHostInfo) ⇒ + * [.getAllHostsFromLedger()](#BaseEvernodeClient+getAllHostsFromLedger) ⇒ + * [.getAllCandidatesFromLedger()](#BaseEvernodeClient+getAllCandidatesFromLedger) ⇒ + * [.pruneDeadHost(hostAddress)](#BaseEvernodeClient+pruneDeadHost) + * [.getCandidateByOwner(ownerAddress)](#BaseEvernodeClient+getCandidateByOwner) ⇒ + * [.getDudHostCandidatesByOwner(ownerAddress)](#BaseEvernodeClient+getDudHostCandidatesByOwner) ⇒ + * [.getCandidateById(candidateId)](#BaseEvernodeClient+getCandidateById) ⇒ + * [.getDudHostVoteInfo(hostAddress)](#BaseEvernodeClient+getDudHostVoteInfo) ⇒ + * [.getPilotedModeVoteInfo()](#BaseEvernodeClient+getPilotedModeVoteInfo) ⇒ + * [.getReputationAddressByOrderedId(orderedId, moment)](#BaseEvernodeClient+getReputationAddressByOrderedId) ⇒ + * [.getReputationOrderByAddress(hostAddress, moment)](#BaseEvernodeClient+getReputationOrderByAddress) ⇒ + * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ + * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + + +### new FoundationClient(xrpAddress, xrpSecret, [options]) +Creates an instance of FoundationClient. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| xrpAddress | string | | The XRP address to associate with this client. | +| xrpSecret | string | | The secret (private key) associated with the XRP address. | +| [options] | Object | {} | Additional configuration options for the FoundationClient. | + + + +### foundationClient.propose(hashes, shortName, options) ⇒ +Propose a new hook candidate. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Proposed candidate id. + +| Param | Type | Description | +| --- | --- | --- | +| hashes | string | Hook candidate hashes in hex format, . | +| shortName | string | Short name for the proposal candidate. | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.withdraw(candidateId, options) ⇒ +Withdraw a hook candidate. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate in hex format. | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.vote(candidateId, vote, options) ⇒ +Vote for a hook candidate. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate in hex format. | +| vote | int | Vote value CandidateVote (0 - Reject, 1 - Support). | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.reportDudHost(hostAddress, options) ⇒ +Report dud host for removal. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | Address of the dud host. | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.voteDudHost(hostAddress, vote, options) ⇒ +Vote for a dud host. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | Address of the dud host. | +| vote | int | Vote value CandidateVote (0 - Reject, 1 - Support). | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.votePilotedMode(vote, options) ⇒ +Vote for a piloted mode. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| vote | int | Vote value CandidateVote (0 - Reject, 1 - Support). | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.changeGovernanceMode(mode, options) ⇒ +Change the governance mode. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| mode | int | Mode (1 - Piloted, 2 - CoPiloted, 3 - AutoPiloted). | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.updateHostReputation(hostAddress, reputation, options) ⇒ +Update the reputation of the host. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | Address of the dud host. | +| reputation | number | Host reputation value. | +| options | \* | [Optional] transaction options. | + + + +### foundationClient.on(event, handler) +Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [on](#BaseEvernodeClient+on) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| handler | function | The callback function to handle the event. The function takes the event object as a parameter. | + + + +### foundationClient.once(event, handler) +Listens to the subscribed events. This will listen only once and detach the handler. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [once](#BaseEvernodeClient+once) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | Event name. | +| handler | function | Callback function to handle the event. | + + + +### foundationClient.off(event, handler) +Detach the listener event. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [off](#BaseEvernodeClient+off) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | Event name. | +| handler | function | | (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified. | + + + +### foundationClient.connect() ⇒ +Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [connect](#BaseEvernodeClient+connect) +**Returns**: Returns `true` if the connection is successful. + + +### foundationClient.disconnect() +Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [disconnect](#BaseEvernodeClient+disconnect) + + +### foundationClient.subscribe() +Subscribes to the client events. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [subscribe](#BaseEvernodeClient+subscribe) + + +### foundationClient.unsubscribe() +Unsubscribes from the client events. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [unsubscribe](#BaseEvernodeClient+unsubscribe) + + +### foundationClient.getEVRBalance() ⇒ +Get the EVR balance in the account. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getEVRBalance](#BaseEvernodeClient+getEVRBalance) +**Returns**: The available EVR amount as a string. + + +### foundationClient.getHookStates() ⇒ +Get all XRPL hook states in the registry account. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getHookStates](#BaseEvernodeClient+getHookStates) +**Returns**: The list of hook states, including Evernode configuration and hosts. + + +### foundationClient.getMoment(index) ⇒ +Get the moment from the given index (timestamp). + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getMoment](#BaseEvernodeClient+getMoment) +**Returns**: The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment value. | + + + +### foundationClient.getMomentStartIndex(index) ⇒ +Get start index (timestamp) of the moment. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getMomentStartIndex](#BaseEvernodeClient+getMomentStartIndex) +**Returns**: The index (timestamp) of the moment as a 'number'. Returns the current moment's start index (timestamp) if ledger index parameter is not given. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment start index. | + + + +### foundationClient.refreshConfig() +Loads the configs from XRPL hook and updates the in-memory config. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [refreshConfig](#BaseEvernodeClient+refreshConfig) + + +### foundationClient.extractEvernodeEvent(tx) ⇒ +Extracts the transaction info from a given transaction. +Note: You need to deserialize HookParameters before passing the transaction to this function. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [extractEvernodeEvent](#BaseEvernodeClient+extractEvernodeEvent) +**Returns**: The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction object to be deserialized and extracted. | + + + +### foundationClient.getHostInfo(hostAddress) ⇒ +Get the registered host information. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getHostInfo](#BaseEvernodeClient+getHostInfo) +**Returns**: The registered host information object. Returns null if not registered. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the host. | + + + +### foundationClient.getAllHostsFromLedger() ⇒ +Get the hosts registered in Evernode. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getAllHostsFromLedger](#BaseEvernodeClient+getAllHostsFromLedger) +**Returns**: The list of hosts. + + +### foundationClient.getAllCandidatesFromLedger() ⇒ +Get the governor in Evernode. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getAllCandidatesFromLedger](#BaseEvernodeClient+getAllCandidatesFromLedger) +**Returns**: The list of candidates. + + +### foundationClient.pruneDeadHost(hostAddress) +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. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [pruneDeadHost](#BaseEvernodeClient+pruneDeadHost) + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to be pruned. | + + + +### foundationClient.getCandidateByOwner(ownerAddress) ⇒ +Get proposed new hook candidate info. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getCandidateByOwner](#BaseEvernodeClient+getCandidateByOwner) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | [Optional] Address of the owner. | + + + +### foundationClient.getDudHostCandidatesByOwner(ownerAddress) ⇒ +Get proposed dud host candidates. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getDudHostCandidatesByOwner](#BaseEvernodeClient+getDudHostCandidatesByOwner) +**Returns**: An array of candidate information. Returns empty array if no candidates. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | | Address of the owner | + + + +### foundationClient.getCandidateById(candidateId) ⇒ +Get candidate info. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getCandidateById](#BaseEvernodeClient+getCandidateById) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate. | + + + +### foundationClient.getDudHostVoteInfo(hostAddress) ⇒ +Get reported dud host info. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getDudHostVoteInfo](#BaseEvernodeClient+getDudHostVoteInfo) +**Returns**: The dud host candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the dud host. | + + + +### foundationClient.getPilotedModeVoteInfo() ⇒ +Get piloted mode vote info. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getPilotedModeVoteInfo](#BaseEvernodeClient+getPilotedModeVoteInfo) +**Returns**: The piloted mode candidate information. Returns null if no candidate. + + +### foundationClient.getReputationAddressByOrderedId(orderedId, moment) ⇒ +Get reputation order info of given orderedId. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getReputationAddressByOrderedId](#BaseEvernodeClient+getReputationAddressByOrderedId) +**Returns**: Reputation address info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| orderedId | number | | Order id of the host. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### foundationClient.getReputationOrderByAddress(hostAddress, moment) ⇒ +Get reputation order info of given host. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getReputationOrderByAddress](#BaseEvernodeClient+getReputationOrderByAddress) +**Returns**: Reputation order info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | (optional) Host address. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### foundationClient.getReputationContractInfoByAddress(hostsAddress, moment) ⇒ +Get reputation contract info of given host. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getReputationContractInfoByAddress](#BaseEvernodeClient+getReputationContractInfoByAddress) +**Returns**: Reputation contract info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | +| moment | number | (optional) Moment to get reputation contract info for. | + + + +### foundationClient.getReputationInfoByAddress(hostsAddress) ⇒ +Get reputation info of given host. + +**Kind**: instance method of [FoundationClient](#FoundationClient) +**Overrides**: [getReputationInfoByAddress](#BaseEvernodeClient+getReputationInfoByAddress) +**Returns**: Reputation info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | + + + +## HeartbeatClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) +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. + +**Kind**: global class +**Extends**: [BaseEvernodeClient](#BaseEvernodeClient) + +* [HeartbeatClient](#HeartbeatClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [.on(event, handler)](#BaseEvernodeClient+on) + * [.once(event, handler)](#BaseEvernodeClient+once) + * [.off(event, handler)](#BaseEvernodeClient+off) + * [.connect()](#BaseEvernodeClient+connect) ⇒ + * [.disconnect()](#BaseEvernodeClient+disconnect) + * [.subscribe()](#BaseEvernodeClient+subscribe) + * [.unsubscribe()](#BaseEvernodeClient+unsubscribe) + * [.getEVRBalance()](#BaseEvernodeClient+getEVRBalance) ⇒ + * [.getHookStates()](#BaseEvernodeClient+getHookStates) ⇒ + * [.getMoment(index)](#BaseEvernodeClient+getMoment) ⇒ + * [.getMomentStartIndex(index)](#BaseEvernodeClient+getMomentStartIndex) ⇒ + * [.refreshConfig()](#BaseEvernodeClient+refreshConfig) + * [.extractEvernodeEvent(tx)](#BaseEvernodeClient+extractEvernodeEvent) ⇒ + * [.getHostInfo(hostAddress)](#BaseEvernodeClient+getHostInfo) ⇒ + * [.getAllHostsFromLedger()](#BaseEvernodeClient+getAllHostsFromLedger) ⇒ + * [.getAllCandidatesFromLedger()](#BaseEvernodeClient+getAllCandidatesFromLedger) ⇒ + * [.pruneDeadHost(hostAddress)](#BaseEvernodeClient+pruneDeadHost) + * [.getCandidateByOwner(ownerAddress)](#BaseEvernodeClient+getCandidateByOwner) ⇒ + * [.getDudHostCandidatesByOwner(ownerAddress)](#BaseEvernodeClient+getDudHostCandidatesByOwner) ⇒ + * [.getCandidateById(candidateId)](#BaseEvernodeClient+getCandidateById) ⇒ + * [.getDudHostVoteInfo(hostAddress)](#BaseEvernodeClient+getDudHostVoteInfo) ⇒ + * [.getPilotedModeVoteInfo()](#BaseEvernodeClient+getPilotedModeVoteInfo) ⇒ + * [.getReputationAddressByOrderedId(orderedId, moment)](#BaseEvernodeClient+getReputationAddressByOrderedId) ⇒ + * [.getReputationOrderByAddress(hostAddress, moment)](#BaseEvernodeClient+getReputationOrderByAddress) ⇒ + * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ + * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + + +### heartbeatClient.on(event, handler) +Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [on](#BaseEvernodeClient+on) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| handler | function | The callback function to handle the event. The function takes the event object as a parameter. | + + + +### heartbeatClient.once(event, handler) +Listens to the subscribed events. This will listen only once and detach the handler. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [once](#BaseEvernodeClient+once) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | Event name. | +| handler | function | Callback function to handle the event. | + + + +### heartbeatClient.off(event, handler) +Detach the listener event. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [off](#BaseEvernodeClient+off) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | Event name. | +| handler | function | | (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified. | + + + +### heartbeatClient.connect() ⇒ +Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [connect](#BaseEvernodeClient+connect) +**Returns**: Returns `true` if the connection is successful. + + +### heartbeatClient.disconnect() +Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [disconnect](#BaseEvernodeClient+disconnect) + + +### heartbeatClient.subscribe() +Subscribes to the client events. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [subscribe](#BaseEvernodeClient+subscribe) + + +### heartbeatClient.unsubscribe() +Unsubscribes from the client events. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [unsubscribe](#BaseEvernodeClient+unsubscribe) + + +### heartbeatClient.getEVRBalance() ⇒ +Get the EVR balance in the account. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getEVRBalance](#BaseEvernodeClient+getEVRBalance) +**Returns**: The available EVR amount as a string. + + +### heartbeatClient.getHookStates() ⇒ +Get all XRPL hook states in the registry account. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getHookStates](#BaseEvernodeClient+getHookStates) +**Returns**: The list of hook states, including Evernode configuration and hosts. + + +### heartbeatClient.getMoment(index) ⇒ +Get the moment from the given index (timestamp). + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getMoment](#BaseEvernodeClient+getMoment) +**Returns**: The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment value. | + + + +### heartbeatClient.getMomentStartIndex(index) ⇒ +Get start index (timestamp) of the moment. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getMomentStartIndex](#BaseEvernodeClient+getMomentStartIndex) +**Returns**: The index (timestamp) of the moment as a 'number'. Returns the current moment's start index (timestamp) if ledger index parameter is not given. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment start index. | + + + +### heartbeatClient.refreshConfig() +Loads the configs from XRPL hook and updates the in-memory config. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [refreshConfig](#BaseEvernodeClient+refreshConfig) + + +### heartbeatClient.extractEvernodeEvent(tx) ⇒ +Extracts the transaction info from a given transaction. +Note: You need to deserialize HookParameters before passing the transaction to this function. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [extractEvernodeEvent](#BaseEvernodeClient+extractEvernodeEvent) +**Returns**: The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction object to be deserialized and extracted. | + + + +### heartbeatClient.getHostInfo(hostAddress) ⇒ +Get the registered host information. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getHostInfo](#BaseEvernodeClient+getHostInfo) +**Returns**: The registered host information object. Returns null if not registered. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the host. | + + + +### heartbeatClient.getAllHostsFromLedger() ⇒ +Get the hosts registered in Evernode. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getAllHostsFromLedger](#BaseEvernodeClient+getAllHostsFromLedger) +**Returns**: The list of hosts. + + +### heartbeatClient.getAllCandidatesFromLedger() ⇒ +Get the governor in Evernode. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getAllCandidatesFromLedger](#BaseEvernodeClient+getAllCandidatesFromLedger) +**Returns**: The list of candidates. + + +### heartbeatClient.pruneDeadHost(hostAddress) +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. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [pruneDeadHost](#BaseEvernodeClient+pruneDeadHost) + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to be pruned. | + + + +### heartbeatClient.getCandidateByOwner(ownerAddress) ⇒ +Get proposed new hook candidate info. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getCandidateByOwner](#BaseEvernodeClient+getCandidateByOwner) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | [Optional] Address of the owner. | + + + +### heartbeatClient.getDudHostCandidatesByOwner(ownerAddress) ⇒ +Get proposed dud host candidates. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getDudHostCandidatesByOwner](#BaseEvernodeClient+getDudHostCandidatesByOwner) +**Returns**: An array of candidate information. Returns empty array if no candidates. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | | Address of the owner | + + + +### heartbeatClient.getCandidateById(candidateId) ⇒ +Get candidate info. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getCandidateById](#BaseEvernodeClient+getCandidateById) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate. | + + + +### heartbeatClient.getDudHostVoteInfo(hostAddress) ⇒ +Get reported dud host info. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getDudHostVoteInfo](#BaseEvernodeClient+getDudHostVoteInfo) +**Returns**: The dud host candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the dud host. | + + + +### heartbeatClient.getPilotedModeVoteInfo() ⇒ +Get piloted mode vote info. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getPilotedModeVoteInfo](#BaseEvernodeClient+getPilotedModeVoteInfo) +**Returns**: The piloted mode candidate information. Returns null if no candidate. + + +### heartbeatClient.getReputationAddressByOrderedId(orderedId, moment) ⇒ +Get reputation order info of given orderedId. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getReputationAddressByOrderedId](#BaseEvernodeClient+getReputationAddressByOrderedId) +**Returns**: Reputation address info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| orderedId | number | | Order id of the host. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### heartbeatClient.getReputationOrderByAddress(hostAddress, moment) ⇒ +Get reputation order info of given host. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getReputationOrderByAddress](#BaseEvernodeClient+getReputationOrderByAddress) +**Returns**: Reputation order info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | (optional) Host address. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### heartbeatClient.getReputationContractInfoByAddress(hostsAddress, moment) ⇒ +Get reputation contract info of given host. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getReputationContractInfoByAddress](#BaseEvernodeClient+getReputationContractInfoByAddress) +**Returns**: Reputation contract info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | +| moment | number | (optional) Moment to get reputation contract info for. | + + + +### heartbeatClient.getReputationInfoByAddress(hostsAddress) ⇒ +Get reputation info of given host. + +**Kind**: instance method of [HeartbeatClient](#HeartbeatClient) +**Overrides**: [getReputationInfoByAddress](#BaseEvernodeClient+getReputationInfoByAddress) +**Returns**: Reputation info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | + + + +## HookClientFactory +A factory class for creating different types of hook clients based on the provided hook type. + +**Kind**: global class + + +### HookClientFactory.create(hookType, [options]) ⇒ Promise.<(Object\|null)> +Creates a hook client from given type. + +**Kind**: static method of [HookClientFactory](#HookClientFactory) +**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. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hookType | string | | Type of the Required Hook. (Supported Hook types 'GOVERNOR', 'REGISTRY', 'HEARTBEAT' and 'REPUTATION') | +| [options] | Object | {} | Optional configuration for the hook client. | + + + +## RegistryClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) +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. + +**Kind**: global class +**Extends**: [BaseEvernodeClient](#BaseEvernodeClient) + +* [RegistryClient](#RegistryClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [.getActiveHostsFromLedger()](#RegistryClient+getActiveHostsFromLedger) ⇒ Promise.<Array> + * [.on(event, handler)](#BaseEvernodeClient+on) + * [.once(event, handler)](#BaseEvernodeClient+once) + * [.off(event, handler)](#BaseEvernodeClient+off) + * [.connect()](#BaseEvernodeClient+connect) ⇒ + * [.disconnect()](#BaseEvernodeClient+disconnect) + * [.subscribe()](#BaseEvernodeClient+subscribe) + * [.unsubscribe()](#BaseEvernodeClient+unsubscribe) + * [.getEVRBalance()](#BaseEvernodeClient+getEVRBalance) ⇒ + * [.getHookStates()](#BaseEvernodeClient+getHookStates) ⇒ + * [.getMoment(index)](#BaseEvernodeClient+getMoment) ⇒ + * [.getMomentStartIndex(index)](#BaseEvernodeClient+getMomentStartIndex) ⇒ + * [.refreshConfig()](#BaseEvernodeClient+refreshConfig) + * [.extractEvernodeEvent(tx)](#BaseEvernodeClient+extractEvernodeEvent) ⇒ + * [.getHostInfo(hostAddress)](#BaseEvernodeClient+getHostInfo) ⇒ + * [.getAllHostsFromLedger()](#BaseEvernodeClient+getAllHostsFromLedger) ⇒ + * [.getAllCandidatesFromLedger()](#BaseEvernodeClient+getAllCandidatesFromLedger) ⇒ + * [.pruneDeadHost(hostAddress)](#BaseEvernodeClient+pruneDeadHost) + * [.getCandidateByOwner(ownerAddress)](#BaseEvernodeClient+getCandidateByOwner) ⇒ + * [.getDudHostCandidatesByOwner(ownerAddress)](#BaseEvernodeClient+getDudHostCandidatesByOwner) ⇒ + * [.getCandidateById(candidateId)](#BaseEvernodeClient+getCandidateById) ⇒ + * [.getDudHostVoteInfo(hostAddress)](#BaseEvernodeClient+getDudHostVoteInfo) ⇒ + * [.getPilotedModeVoteInfo()](#BaseEvernodeClient+getPilotedModeVoteInfo) ⇒ + * [.getReputationAddressByOrderedId(orderedId, moment)](#BaseEvernodeClient+getReputationAddressByOrderedId) ⇒ + * [.getReputationOrderByAddress(hostAddress, moment)](#BaseEvernodeClient+getReputationOrderByAddress) ⇒ + * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ + * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + + +### registryClient.getActiveHostsFromLedger() ⇒ Promise.<Array> +Retrieves all active hosts registered in the ledger. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Returns**: Promise.<Array> - - A promise that resolves to an array of active hosts. + + +### registryClient.on(event, handler) +Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [on](#BaseEvernodeClient+on) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| handler | function | The callback function to handle the event. The function takes the event object as a parameter. | + + + +### registryClient.once(event, handler) +Listens to the subscribed events. This will listen only once and detach the handler. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [once](#BaseEvernodeClient+once) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | Event name. | +| handler | function | Callback function to handle the event. | + + + +### registryClient.off(event, handler) +Detach the listener event. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [off](#BaseEvernodeClient+off) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | Event name. | +| handler | function | | (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified. | + + + +### registryClient.connect() ⇒ +Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [connect](#BaseEvernodeClient+connect) +**Returns**: Returns `true` if the connection is successful. + + +### registryClient.disconnect() +Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [disconnect](#BaseEvernodeClient+disconnect) + + +### registryClient.subscribe() +Subscribes to the client events. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [subscribe](#BaseEvernodeClient+subscribe) + + +### registryClient.unsubscribe() +Unsubscribes from the client events. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [unsubscribe](#BaseEvernodeClient+unsubscribe) + + +### registryClient.getEVRBalance() ⇒ +Get the EVR balance in the account. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getEVRBalance](#BaseEvernodeClient+getEVRBalance) +**Returns**: The available EVR amount as a string. + + +### registryClient.getHookStates() ⇒ +Get all XRPL hook states in the registry account. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getHookStates](#BaseEvernodeClient+getHookStates) +**Returns**: The list of hook states, including Evernode configuration and hosts. + + +### registryClient.getMoment(index) ⇒ +Get the moment from the given index (timestamp). + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getMoment](#BaseEvernodeClient+getMoment) +**Returns**: The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment value. | + + + +### registryClient.getMomentStartIndex(index) ⇒ +Get start index (timestamp) of the moment. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getMomentStartIndex](#BaseEvernodeClient+getMomentStartIndex) +**Returns**: The index (timestamp) of the moment as a 'number'. Returns the current moment's start index (timestamp) if ledger index parameter is not given. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment start index. | + + + +### registryClient.refreshConfig() +Loads the configs from XRPL hook and updates the in-memory config. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [refreshConfig](#BaseEvernodeClient+refreshConfig) + + +### registryClient.extractEvernodeEvent(tx) ⇒ +Extracts the transaction info from a given transaction. +Note: You need to deserialize HookParameters before passing the transaction to this function. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [extractEvernodeEvent](#BaseEvernodeClient+extractEvernodeEvent) +**Returns**: The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction object to be deserialized and extracted. | + + + +### registryClient.getHostInfo(hostAddress) ⇒ +Get the registered host information. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getHostInfo](#BaseEvernodeClient+getHostInfo) +**Returns**: The registered host information object. Returns null if not registered. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the host. | + + + +### registryClient.getAllHostsFromLedger() ⇒ +Get the hosts registered in Evernode. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getAllHostsFromLedger](#BaseEvernodeClient+getAllHostsFromLedger) +**Returns**: The list of hosts. + + +### registryClient.getAllCandidatesFromLedger() ⇒ +Get the governor in Evernode. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getAllCandidatesFromLedger](#BaseEvernodeClient+getAllCandidatesFromLedger) +**Returns**: The list of candidates. + + +### registryClient.pruneDeadHost(hostAddress) +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. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [pruneDeadHost](#BaseEvernodeClient+pruneDeadHost) + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to be pruned. | + + + +### registryClient.getCandidateByOwner(ownerAddress) ⇒ +Get proposed new hook candidate info. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getCandidateByOwner](#BaseEvernodeClient+getCandidateByOwner) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | [Optional] Address of the owner. | + + + +### registryClient.getDudHostCandidatesByOwner(ownerAddress) ⇒ +Get proposed dud host candidates. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getDudHostCandidatesByOwner](#BaseEvernodeClient+getDudHostCandidatesByOwner) +**Returns**: An array of candidate information. Returns empty array if no candidates. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | | Address of the owner | + + + +### registryClient.getCandidateById(candidateId) ⇒ +Get candidate info. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getCandidateById](#BaseEvernodeClient+getCandidateById) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate. | + + + +### registryClient.getDudHostVoteInfo(hostAddress) ⇒ +Get reported dud host info. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getDudHostVoteInfo](#BaseEvernodeClient+getDudHostVoteInfo) +**Returns**: The dud host candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the dud host. | + + + +### registryClient.getPilotedModeVoteInfo() ⇒ +Get piloted mode vote info. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getPilotedModeVoteInfo](#BaseEvernodeClient+getPilotedModeVoteInfo) +**Returns**: The piloted mode candidate information. Returns null if no candidate. + + +### registryClient.getReputationAddressByOrderedId(orderedId, moment) ⇒ +Get reputation order info of given orderedId. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getReputationAddressByOrderedId](#BaseEvernodeClient+getReputationAddressByOrderedId) +**Returns**: Reputation address info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| orderedId | number | | Order id of the host. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### registryClient.getReputationOrderByAddress(hostAddress, moment) ⇒ +Get reputation order info of given host. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getReputationOrderByAddress](#BaseEvernodeClient+getReputationOrderByAddress) +**Returns**: Reputation order info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | (optional) Host address. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### registryClient.getReputationContractInfoByAddress(hostsAddress, moment) ⇒ +Get reputation contract info of given host. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getReputationContractInfoByAddress](#BaseEvernodeClient+getReputationContractInfoByAddress) +**Returns**: Reputation contract info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | +| moment | number | (optional) Moment to get reputation contract info for. | + + + +### registryClient.getReputationInfoByAddress(hostsAddress) ⇒ +Get reputation info of given host. + +**Kind**: instance method of [RegistryClient](#RegistryClient) +**Overrides**: [getReputationInfoByAddress](#BaseEvernodeClient+getReputationInfoByAddress) +**Returns**: Reputation info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | + + + +## HostClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) +HostClient class to manage host operations. +It extends the BaseEvernodeClient. + +**Kind**: global class +**Extends**: [BaseEvernodeClient](#BaseEvernodeClient) + +* [HostClient](#HostClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [new HostClient(xrpAddress, xrpSecret, [options])](#new_HostClient_new) + * [.getRegistrationUriToken()](#HostClient+getRegistrationUriToken) ⇒ + * [.getRegistration()](#HostClient+getRegistration) ⇒ + * [.getLeaseByIndex(index)](#HostClient+getLeaseByIndex) ⇒ + * [.getLeases()](#HostClient+getLeases) ⇒ + * [.getLeaseOffers()](#HostClient+getLeaseOffers) ⇒ + * [.getUnofferedLeases()](#HostClient+getUnofferedLeases) ⇒ + * [.isRegistered()](#HostClient+isRegistered) ⇒ + * [.prepareAccount(domain)](#HostClient+prepareAccount) + * [.prepareReputationAccount(reputationAddress, reputationSecret)](#HostClient+prepareReputationAccount) + * [.setReputationContractInfo(peerPort, publicKey)](#HostClient+setReputationContractInfo) + * [.getReputationInfo(moment)](#HostClient+getReputationInfo) ⇒ + * [.prepareHostReputationScores(scoreVersion, clusterSize, collectedScores)](#HostClient+prepareHostReputationScores) ⇒ + * [.sendReputations(bufferHex)](#HostClient+sendReputations) + * [.offerLease(leaseIndex, leaseAmount, tosHash, outboundIPAddress)](#HostClient+offerLease) + * [.mintLease(leaseIndex, leaseAmount, tosHash, outboundIPAddress)](#HostClient+mintLease) + * [.offerMintedLease(uriTokenId, leaseAmount)](#HostClient+offerMintedLease) + * [.expireLease(uriTokenId)](#HostClient+expireLease) + * [.acceptRegToken(options)](#HostClient+acceptRegToken) ⇒ + * [.register(countryCode, cpuMicroSec, ramMb, diskMb, totalInstanceCount, cpuModel, cpuCount, cpuSpeed, description, emailAddress, leaseAmount, options)](#HostClient+register) ⇒ + * [.deregister(error, options)](#HostClient+deregister) ⇒ + * [.updateRegInfo(activeInstanceCount, version, totalInstanceCount, tokenID, countryCode, cpuMicroSec, ramMb, diskMb, description, emailAddress, leaseAmount, options)](#HostClient+updateRegInfo) ⇒ + * [.heartbeat(voteInfo, options)](#HostClient+heartbeat) ⇒ + * [.acquireSuccess(txHash, tenantAddress, instanceInfo, options)](#HostClient+acquireSuccess) ⇒ + * [.acquireError(txHash, tenantAddress, leaseAmount, reason, options)](#HostClient+acquireError) ⇒ + * [.extendSuccess(txHash, tenantAddress, expiryMoment, options)](#HostClient+extendSuccess) ⇒ + * [.extendError(txHash, tenantAddress, reason, refund, options)](#HostClient+extendError) ⇒ + * [.refundTenant(txHash, tenantAddress, refundAmount, options)](#HostClient+refundTenant) ⇒ + * [.requestRebate(options)](#HostClient+requestRebate) ⇒ + * [.transfer(transfereeAddress, options)](#HostClient+transfer) + * [.isTransferee()](#HostClient+isTransferee) ⇒ + * [.propose(hashes, shortName, options)](#HostClient+propose) ⇒ + * [.withdraw(candidateId, options)](#HostClient+withdraw) ⇒ + * [.reportDudHost(hostAddress, options)](#HostClient+reportDudHost) ⇒ + * [.on(event, handler)](#BaseEvernodeClient+on) + * [.once(event, handler)](#BaseEvernodeClient+once) + * [.off(event, handler)](#BaseEvernodeClient+off) + * [.connect()](#BaseEvernodeClient+connect) ⇒ + * [.disconnect()](#BaseEvernodeClient+disconnect) + * [.subscribe()](#BaseEvernodeClient+subscribe) + * [.unsubscribe()](#BaseEvernodeClient+unsubscribe) + * [.getEVRBalance()](#BaseEvernodeClient+getEVRBalance) ⇒ + * [.getHookStates()](#BaseEvernodeClient+getHookStates) ⇒ + * [.getMoment(index)](#BaseEvernodeClient+getMoment) ⇒ + * [.getMomentStartIndex(index)](#BaseEvernodeClient+getMomentStartIndex) ⇒ + * [.refreshConfig()](#BaseEvernodeClient+refreshConfig) + * [.extractEvernodeEvent(tx)](#BaseEvernodeClient+extractEvernodeEvent) ⇒ + * [.getHostInfo(hostAddress)](#BaseEvernodeClient+getHostInfo) ⇒ + * [.getAllHostsFromLedger()](#BaseEvernodeClient+getAllHostsFromLedger) ⇒ + * [.getAllCandidatesFromLedger()](#BaseEvernodeClient+getAllCandidatesFromLedger) ⇒ + * [.pruneDeadHost(hostAddress)](#BaseEvernodeClient+pruneDeadHost) + * [.getCandidateByOwner(ownerAddress)](#BaseEvernodeClient+getCandidateByOwner) ⇒ + * [.getDudHostCandidatesByOwner(ownerAddress)](#BaseEvernodeClient+getDudHostCandidatesByOwner) ⇒ + * [.getCandidateById(candidateId)](#BaseEvernodeClient+getCandidateById) ⇒ + * [.getDudHostVoteInfo(hostAddress)](#BaseEvernodeClient+getDudHostVoteInfo) ⇒ + * [.getPilotedModeVoteInfo()](#BaseEvernodeClient+getPilotedModeVoteInfo) ⇒ + * [.getReputationAddressByOrderedId(orderedId, moment)](#BaseEvernodeClient+getReputationAddressByOrderedId) ⇒ + * [.getReputationOrderByAddress(hostAddress, moment)](#BaseEvernodeClient+getReputationOrderByAddress) ⇒ + * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ + * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + + +### new HostClient(xrpAddress, xrpSecret, [options]) +Creates an instance of HostClient. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| xrpAddress | string | | The XRP address to associate with this client. | +| xrpSecret | string | | The secret (private key) associated with the XRP address. | +| [options] | Object | {} | Additional configuration options for the HostClient. | + + + +### hostClient.getRegistrationUriToken() ⇒ +Get registration URI token info. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: The registration URI token object. + + +### hostClient.getRegistration() ⇒ +Get host info if registered. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Host info object if registered, Otherwise null. + + +### hostClient.getLeaseByIndex(index) ⇒ +Get lease token by index. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Lease token. + +| Param | Description | +| --- | --- | +| index | Index of the token. | + + + +### hostClient.getLeases() ⇒ +Get offered and unoffered leases created by the host. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Array of lease offer objects. + + +### hostClient.getLeaseOffers() ⇒ +Get lease offers created by the host. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Array of lease offer objects. + + +### hostClient.getUnofferedLeases() ⇒ +Get unoffered leases created by the host. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Array of lease objects. + + +### hostClient.isRegistered() ⇒ +Check wether the host is registered. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Boolean if the host is registered or not. + + +### hostClient.prepareAccount(domain) +Prepare the host account with account fields and trust lines. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Description | +| --- | --- | --- | +| domain | string | Domain which the host machine is reachable. | + + + +### hostClient.prepareReputationAccount(reputationAddress, reputationSecret) +Prepare the reputation account with account fields and trust lines. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Description | +| --- | --- | --- | +| reputationAddress | string | Address of the reputation account. | +| reputationSecret | string | Secret of the reputation account. | + + + +### hostClient.setReputationContractInfo(peerPort, publicKey) +Set the reputation contract info. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Description | +| --- | --- | --- | +| peerPort | number | Peer port of the reputation contract instance. | +| publicKey | string | Public key of the reputation contract instance. | + + + +### hostClient.getReputationInfo(moment) ⇒ +Get reputation info of this host. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Reputation info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### hostClient.prepareHostReputationScores(scoreVersion, clusterSize, collectedScores) ⇒ +Prepare host reputation score to a common format for submission. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Unified reputation score buffer. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| scoreVersion | number | | Version of the scores. | +| clusterSize | number | | Size of the cluster. | +| collectedScores | object | | [Optional] Score object in { host: score } format. | + + + +### hostClient.sendReputations(bufferHex) +Send reputation scores to the reputation hook. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Description | +| --- | --- | --- | +| bufferHex | string | Prepared score buffer as hex string. | + + + +### hostClient.offerLease(leaseIndex, leaseAmount, tosHash, outboundIPAddress) +Create a lease offer. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| leaseIndex | number | | Index number for the lease. | +| leaseAmount | number | | Amount (EVRs) of the lease offer. | +| tosHash | string | | Hex hash of the Terms Of Service text. | +| outboundIPAddress | string | null | Assigned IP Address. | + + + +### hostClient.mintLease(leaseIndex, leaseAmount, tosHash, outboundIPAddress) +Mint a lease offer. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| leaseIndex | number | | Index number for the lease. | +| leaseAmount | number | | Amount (EVRs) of the lease offer. | +| tosHash | string | | Hex hash of the Terms Of Service text. | +| outboundIPAddress | string | null | Assigned IP Address. | + + + +### hostClient.offerMintedLease(uriTokenId, leaseAmount) +Create a lease offer. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Description | +| --- | --- | --- | +| uriTokenId | number | Id of the token. | +| leaseAmount | number | Amount (EVRs) of the lease offer. | + + + +### hostClient.expireLease(uriTokenId) +Expire the lease offer. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Description | +| --- | --- | --- | +| uriTokenId | string | Hex URI token id of the lease. | + + + +### hostClient.acceptRegToken(options) ⇒ +Accepts if there's an available reg token. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: True if there were reg token and it's accepted, Otherwise false. + +| Param | Type | Description | +| --- | --- | --- | +| options | \* | [Optional] transaction options. | + + + +### hostClient.register(countryCode, cpuMicroSec, ramMb, diskMb, totalInstanceCount, cpuModel, cpuCount, cpuSpeed, description, emailAddress, leaseAmount, options) ⇒ +Register the host in the Evernode network. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| countryCode | string | Upper case country code with two letters. | +| cpuMicroSec | number | CPU cycle in micro seconds of the host. | +| ramMb | number | Ram size in mega bytes. | +| diskMb | number | Disk size in mega bytes. | +| totalInstanceCount | number | Total number of instance slots in the host. | +| cpuModel | string | Model of the host CPU. | +| cpuCount | number | Number of CPUs in the host. | +| cpuSpeed | number | CPU MHz. | +| description | string | Description about the host. | +| emailAddress | string | Email address of the host. | +| leaseAmount | number | Lease fee of the host. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.deregister(error, options) ⇒ +Deregister a host from the Evernode network. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Boolean whether host is registered or not. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| error | string | null | [Optional] Error. | +| options | \* | | [Optional] transaction options. | + + + +### hostClient.updateRegInfo(activeInstanceCount, version, totalInstanceCount, tokenID, countryCode, cpuMicroSec, ramMb, diskMb, description, emailAddress, leaseAmount, options) ⇒ +Update the host registration in the Evernode network. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| activeInstanceCount | number | | Currently active instance count in the host. | +| version | string | null | Sashimono version installed on the host | +| totalInstanceCount | number | | Total number of instance slots in the host. | +| tokenID | string | null | Registration Token Id of the host. | +| countryCode | string | null | Upper case country code with two letters. | +| cpuMicroSec | number | | | +| ramMb | number | | Ram size in mega bytes. | +| diskMb | number | | Disk size in mega bytes. | +| description | string | null | Description about the host. | +| emailAddress | string | null | Email address of the host. | +| leaseAmount | number | | Lease fee of the host. | +| options | \* | | [Optional] transaction options. | + + + +### hostClient.heartbeat(voteInfo, options) ⇒ +Send a heartbeat from the host. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| voteInfo | \* | [Optional] Candidate votes if there's any `{ '': '{number 0|1} vote', ... }` | +| options | \* | [Optional] transaction options. | + + + +### hostClient.acquireSuccess(txHash, tenantAddress, instanceInfo, options) ⇒ +Send acquire success response to the tenant. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| txHash | string | Acquire lease transaction hash in hex. | +| tenantAddress | string | XRPL address of the tenant. | +| instanceInfo | string | Created instance info. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.acquireError(txHash, tenantAddress, leaseAmount, reason, options) ⇒ +Send acquire error response to the tenant. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| txHash | string | Acquire lease transaction hash in hex. | +| tenantAddress | string | Xrpl address of the tenant. | +| leaseAmount | number | Lease amount to be refunded. | +| reason | string | Reason for the error. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.extendSuccess(txHash, tenantAddress, expiryMoment, options) ⇒ +Send extend success response to the tenant. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| txHash | string | Extend lease transaction hash in hex. | +| tenantAddress | string | XRPL address of the tenant. | +| expiryMoment | number | Moment which the instance will expire. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.extendError(txHash, tenantAddress, reason, refund, options) ⇒ +Send extend error response to the tenant. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| txHash | string | Extend lease transaction hash in hex. | +| tenantAddress | string | Xrpl address of the tenant. | +| reason | string | Reason for the error. | +| refund | number | Amount to be refunded. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.refundTenant(txHash, tenantAddress, refundAmount, options) ⇒ +Send refunds to the tenant. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| txHash | string | Request transaction hash in hex. | +| tenantAddress | string | Xrpl address of the tenant. | +| refundAmount | number | Amount to be refunded. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.requestRebate(options) ⇒ +Request registration rebates from the registry. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| options | \* | [Optional] transaction options. | + + + +### hostClient.transfer(transfereeAddress, options) +Initiate a host transfer. + +**Kind**: instance method of [HostClient](#HostClient) + +| Param | Type | Description | +| --- | --- | --- | +| transfereeAddress | string | [Optional] Xrpl account address to host registration to be transferred. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.isTransferee() ⇒ +Check whether this host is a transferee. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Boolean wether the host is a transferee or not. + + +### hostClient.propose(hashes, shortName, options) ⇒ +Propose a new hook candidate. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Proposed candidate id. + +| Param | Type | Description | +| --- | --- | --- | +| hashes | string | Hook candidate hashes in hex format, . | +| shortName | string | Short name for the proposal candidate. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.withdraw(candidateId, options) ⇒ +Withdraw a hook candidate. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate in hex format. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.reportDudHost(hostAddress, options) ⇒ +Report dud host for removal. + +**Kind**: instance method of [HostClient](#HostClient) +**Returns**: Transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | Address of the dud host. | +| options | \* | [Optional] transaction options. | + + + +### hostClient.on(event, handler) +Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [on](#BaseEvernodeClient+on) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| handler | function | The callback function to handle the event. The function takes the event object as a parameter. | + + + +### hostClient.once(event, handler) +Listens to the subscribed events. This will listen only once and detach the handler. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [once](#BaseEvernodeClient+once) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | Event name. | +| handler | function | Callback function to handle the event. | + + + +### hostClient.off(event, handler) +Detach the listener event. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [off](#BaseEvernodeClient+off) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | Event name. | +| handler | function | | (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified. | + + + +### hostClient.connect() ⇒ +Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [connect](#BaseEvernodeClient+connect) +**Returns**: Returns `true` if the connection is successful. + + +### hostClient.disconnect() +Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [disconnect](#BaseEvernodeClient+disconnect) + + +### hostClient.subscribe() +Subscribes to the client events. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [subscribe](#BaseEvernodeClient+subscribe) + + +### hostClient.unsubscribe() +Unsubscribes from the client events. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [unsubscribe](#BaseEvernodeClient+unsubscribe) + + +### hostClient.getEVRBalance() ⇒ +Get the EVR balance in the account. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getEVRBalance](#BaseEvernodeClient+getEVRBalance) +**Returns**: The available EVR amount as a string. + + +### hostClient.getHookStates() ⇒ +Get all XRPL hook states in the registry account. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getHookStates](#BaseEvernodeClient+getHookStates) +**Returns**: The list of hook states, including Evernode configuration and hosts. + + +### hostClient.getMoment(index) ⇒ +Get the moment from the given index (timestamp). + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getMoment](#BaseEvernodeClient+getMoment) +**Returns**: The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment value. | + + + +### hostClient.getMomentStartIndex(index) ⇒ +Get start index (timestamp) of the moment. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getMomentStartIndex](#BaseEvernodeClient+getMomentStartIndex) +**Returns**: The index (timestamp) of the moment as a 'number'. Returns the current moment's start index (timestamp) if ledger index parameter is not given. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment start index. | + + + +### hostClient.refreshConfig() +Loads the configs from XRPL hook and updates the in-memory config. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [refreshConfig](#BaseEvernodeClient+refreshConfig) + + +### hostClient.extractEvernodeEvent(tx) ⇒ +Extracts the transaction info from a given transaction. +Note: You need to deserialize HookParameters before passing the transaction to this function. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [extractEvernodeEvent](#BaseEvernodeClient+extractEvernodeEvent) +**Returns**: The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction object to be deserialized and extracted. | + + + +### hostClient.getHostInfo(hostAddress) ⇒ +Get the registered host information. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getHostInfo](#BaseEvernodeClient+getHostInfo) +**Returns**: The registered host information object. Returns null if not registered. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the host. | + + + +### hostClient.getAllHostsFromLedger() ⇒ +Get the hosts registered in Evernode. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getAllHostsFromLedger](#BaseEvernodeClient+getAllHostsFromLedger) +**Returns**: The list of hosts. + + +### hostClient.getAllCandidatesFromLedger() ⇒ +Get the governor in Evernode. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getAllCandidatesFromLedger](#BaseEvernodeClient+getAllCandidatesFromLedger) +**Returns**: The list of candidates. + + +### hostClient.pruneDeadHost(hostAddress) +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. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [pruneDeadHost](#BaseEvernodeClient+pruneDeadHost) + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to be pruned. | + + + +### hostClient.getCandidateByOwner(ownerAddress) ⇒ +Get proposed new hook candidate info. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getCandidateByOwner](#BaseEvernodeClient+getCandidateByOwner) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | [Optional] Address of the owner. | + + + +### hostClient.getDudHostCandidatesByOwner(ownerAddress) ⇒ +Get proposed dud host candidates. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getDudHostCandidatesByOwner](#BaseEvernodeClient+getDudHostCandidatesByOwner) +**Returns**: An array of candidate information. Returns empty array if no candidates. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | | Address of the owner | + + + +### hostClient.getCandidateById(candidateId) ⇒ +Get candidate info. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getCandidateById](#BaseEvernodeClient+getCandidateById) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate. | + + + +### hostClient.getDudHostVoteInfo(hostAddress) ⇒ +Get reported dud host info. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getDudHostVoteInfo](#BaseEvernodeClient+getDudHostVoteInfo) +**Returns**: The dud host candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the dud host. | + + + +### hostClient.getPilotedModeVoteInfo() ⇒ +Get piloted mode vote info. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getPilotedModeVoteInfo](#BaseEvernodeClient+getPilotedModeVoteInfo) +**Returns**: The piloted mode candidate information. Returns null if no candidate. + + +### hostClient.getReputationAddressByOrderedId(orderedId, moment) ⇒ +Get reputation order info of given orderedId. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getReputationAddressByOrderedId](#BaseEvernodeClient+getReputationAddressByOrderedId) +**Returns**: Reputation address info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| orderedId | number | | Order id of the host. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### hostClient.getReputationOrderByAddress(hostAddress, moment) ⇒ +Get reputation order info of given host. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getReputationOrderByAddress](#BaseEvernodeClient+getReputationOrderByAddress) +**Returns**: Reputation order info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | (optional) Host address. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### hostClient.getReputationContractInfoByAddress(hostsAddress, moment) ⇒ +Get reputation contract info of given host. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getReputationContractInfoByAddress](#BaseEvernodeClient+getReputationContractInfoByAddress) +**Returns**: Reputation contract info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | +| moment | number | (optional) Moment to get reputation contract info for. | + + + +### hostClient.getReputationInfoByAddress(hostsAddress) ⇒ +Get reputation info of given host. + +**Kind**: instance method of [HostClient](#HostClient) +**Overrides**: [getReputationInfoByAddress](#BaseEvernodeClient+getReputationInfoByAddress) +**Returns**: Reputation info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | + + + +## TenantClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) +TenantClient class to manage tenant operations. +It extends the BaseEvernodeClient. + +**Kind**: global class +**Extends**: [BaseEvernodeClient](#BaseEvernodeClient) + +* [TenantClient](#TenantClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [new TenantClient(xrpAddress, xrpSecret, [options])](#new_TenantClient_new) + * [.prepareAccount([options])](#TenantClient+prepareAccount) + * [.getLeaseHost(hostAddress)](#TenantClient+getLeaseHost) ⇒ Promise.<Object> + * [.acquireLeaseSubmit(hostAddress, requirement, options)](#TenantClient+acquireLeaseSubmit) ⇒ + * [.prepareAcquireLeaseTransaction(hostAddress, requirement, options)](#TenantClient+prepareAcquireLeaseTransaction) ⇒ + * [.watchAcquireResponse(tx, options)](#TenantClient+watchAcquireResponse) ⇒ + * [.acquireLease(hostAddress, requirement, options)](#TenantClient+acquireLease) ⇒ + * [.extendLeaseSubmit(hostAddress, amount, tokenID, options)](#TenantClient+extendLeaseSubmit) ⇒ + * [.prepareExtendLeaseTransaction(hostAddress, amount, tokenID, options)](#TenantClient+prepareExtendLeaseTransaction) ⇒ + * [.watchExtendResponse(tx, options)](#TenantClient+watchExtendResponse) ⇒ + * [.extendLease(hostAddress, moments, instanceName, options)](#TenantClient+extendLease) ⇒ + * [.terminateLease(uriTokenId)](#TenantClient+terminateLease) + * [.on(event, handler)](#BaseEvernodeClient+on) + * [.once(event, handler)](#BaseEvernodeClient+once) + * [.off(event, handler)](#BaseEvernodeClient+off) + * [.connect()](#BaseEvernodeClient+connect) ⇒ + * [.disconnect()](#BaseEvernodeClient+disconnect) + * [.subscribe()](#BaseEvernodeClient+subscribe) + * [.unsubscribe()](#BaseEvernodeClient+unsubscribe) + * [.getEVRBalance()](#BaseEvernodeClient+getEVRBalance) ⇒ + * [.getHookStates()](#BaseEvernodeClient+getHookStates) ⇒ + * [.getMoment(index)](#BaseEvernodeClient+getMoment) ⇒ + * [.getMomentStartIndex(index)](#BaseEvernodeClient+getMomentStartIndex) ⇒ + * [.refreshConfig()](#BaseEvernodeClient+refreshConfig) + * [.extractEvernodeEvent(tx)](#BaseEvernodeClient+extractEvernodeEvent) ⇒ + * [.getHostInfo(hostAddress)](#BaseEvernodeClient+getHostInfo) ⇒ + * [.getAllHostsFromLedger()](#BaseEvernodeClient+getAllHostsFromLedger) ⇒ + * [.getAllCandidatesFromLedger()](#BaseEvernodeClient+getAllCandidatesFromLedger) ⇒ + * [.pruneDeadHost(hostAddress)](#BaseEvernodeClient+pruneDeadHost) + * [.getCandidateByOwner(ownerAddress)](#BaseEvernodeClient+getCandidateByOwner) ⇒ + * [.getDudHostCandidatesByOwner(ownerAddress)](#BaseEvernodeClient+getDudHostCandidatesByOwner) ⇒ + * [.getCandidateById(candidateId)](#BaseEvernodeClient+getCandidateById) ⇒ + * [.getDudHostVoteInfo(hostAddress)](#BaseEvernodeClient+getDudHostVoteInfo) ⇒ + * [.getPilotedModeVoteInfo()](#BaseEvernodeClient+getPilotedModeVoteInfo) ⇒ + * [.getReputationAddressByOrderedId(orderedId, moment)](#BaseEvernodeClient+getReputationAddressByOrderedId) ⇒ + * [.getReputationOrderByAddress(hostAddress, moment)](#BaseEvernodeClient+getReputationOrderByAddress) ⇒ + * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ + * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + + +### new TenantClient(xrpAddress, xrpSecret, [options]) +Creates an instance of TenantClient. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| xrpAddress | string | | The XRP address to associate with this client. | +| xrpSecret | string | | The secret (private key) associated with the XRP address. | +| [options] | Object | {} | Additional configuration options for the TenantClient. | + + + +### tenantClient.prepareAccount([options]) +Prepare the tenant account with account fields and trust lines. + +**Kind**: instance method of [TenantClient](#TenantClient) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [options] | Object | {} | Optional configuration for the account setup. | + + + +### tenantClient.getLeaseHost(hostAddress) ⇒ Promise.<Object> +Retrieves and validates a lease host based on the given host address. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: Promise.<Object> - - Returns the host object if valid and active. +**Throws**: + +- Will throw an error if the host is invalid, inactive, or not registered. + + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | The XRP Ledger address of the host. | + + + +### tenantClient.acquireLeaseSubmit(hostAddress, requirement, options) ⇒ +Prepare and submit acquire transaction.(Single signed scenario) + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: The transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to acquire the lease. | +| requirement | object | The instance requirements and configuration. | +| options | object | [Optional] Options for the XRPL transaction. | + + + +### tenantClient.prepareAcquireLeaseTransaction(hostAddress, requirement, options) ⇒ +Prepare the Acquire transaction. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: Prepared Acquire transaction. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to acquire the lease. | +| requirement | object | The instance requirements and configuration. | +| options | object | [Optional] Options for the XRPL transaction. | + + + +### tenantClient.watchAcquireResponse(tx, options) ⇒ +Watch for the acquire-success response after the acquire request is made. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: An object including transaction details,instance info, and acquireReference Id. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction returned by the acquireLeaseSubmit function. | +| options | object | [Optional] Options for the XRPL transaction. | + + + +### tenantClient.acquireLease(hostAddress, requirement, options) ⇒ +Acquire an instance from a host + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: An object including transaction details,instance info, and acquireReference Id. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to acquire the lease. | +| requirement | object | The instance requirements and configuration. | +| options | object | [Optional] Options for the XRPL transaction. | + + + +### tenantClient.extendLeaseSubmit(hostAddress, amount, tokenID, options) ⇒ +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. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: The transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL account address of the host. | +| amount | number | Cost for the extended moments , in EVRs. | +| tokenID | string | Tenant received instance name. this name can be retrieve by performing acquire Lease. | +| options | object | This is an optional field and contains necessary details for the transactions. | + + + +### tenantClient.prepareExtendLeaseTransaction(hostAddress, amount, tokenID, options) ⇒ +This function is called to prepare an instance extension transaction for a particular host. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: The prepared transaction. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL account address of the host. | +| amount | number | Cost for the extended moments , in EVRs. | +| tokenID | string | Tenant received instance name. this name can be retrieve by performing acquire Lease. | +| options | object | This is an optional field and contains necessary details for the transactions. | + + + +### tenantClient.watchExtendResponse(tx, 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. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: An object including transaction details. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | Response of extendLeaseSubmit. | +| options | object | This is an optional field and contains necessary details for the transactions. | + + + +### tenantClient.extendLease(hostAddress, moments, instanceName, options) ⇒ +This function is called by a tenant client to extend an available instance in certain host. This function can take four parameters as follows. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Returns**: An object including transaction details. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL account address of the host. | +| moments | number | 1190 ledgers (est. 1 hour). | +| instanceName | string | Tenant received instance name. this name can be retrieve by performing acquire Lease. | +| options | object | This is an optional field and contains necessary details for the transactions. | + + + +### tenantClient.terminateLease(uriTokenId) +Terminate the lease instance. + +**Kind**: instance method of [TenantClient](#TenantClient) + +| Param | Type | Description | +| --- | --- | --- | +| uriTokenId | string | Hex URI token id of the lease. | + + + +### tenantClient.on(event, handler) +Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [on](#BaseEvernodeClient+on) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| handler | function | The callback function to handle the event. The function takes the event object as a parameter. | + + + +### tenantClient.once(event, handler) +Listens to the subscribed events. This will listen only once and detach the handler. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [once](#BaseEvernodeClient+once) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | Event name. | +| handler | function | Callback function to handle the event. | + + + +### tenantClient.off(event, handler) +Detach the listener event. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [off](#BaseEvernodeClient+off) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | Event name. | +| handler | function | | (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified. | + + + +### tenantClient.connect() ⇒ +Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [connect](#BaseEvernodeClient+connect) +**Returns**: Returns `true` if the connection is successful. + + +### tenantClient.disconnect() +Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [disconnect](#BaseEvernodeClient+disconnect) + + +### tenantClient.subscribe() +Subscribes to the client events. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [subscribe](#BaseEvernodeClient+subscribe) + + +### tenantClient.unsubscribe() +Unsubscribes from the client events. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [unsubscribe](#BaseEvernodeClient+unsubscribe) + + +### tenantClient.getEVRBalance() ⇒ +Get the EVR balance in the account. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getEVRBalance](#BaseEvernodeClient+getEVRBalance) +**Returns**: The available EVR amount as a string. + + +### tenantClient.getHookStates() ⇒ +Get all XRPL hook states in the registry account. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getHookStates](#BaseEvernodeClient+getHookStates) +**Returns**: The list of hook states, including Evernode configuration and hosts. + + +### tenantClient.getMoment(index) ⇒ +Get the moment from the given index (timestamp). + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getMoment](#BaseEvernodeClient+getMoment) +**Returns**: The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment value. | + + + +### tenantClient.getMomentStartIndex(index) ⇒ +Get start index (timestamp) of the moment. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getMomentStartIndex](#BaseEvernodeClient+getMomentStartIndex) +**Returns**: The index (timestamp) of the moment as a 'number'. Returns the current moment's start index (timestamp) if ledger index parameter is not given. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment start index. | + + + +### tenantClient.refreshConfig() +Loads the configs from XRPL hook and updates the in-memory config. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [refreshConfig](#BaseEvernodeClient+refreshConfig) + + +### tenantClient.extractEvernodeEvent(tx) ⇒ +Extracts the transaction info from a given transaction. +Note: You need to deserialize HookParameters before passing the transaction to this function. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [extractEvernodeEvent](#BaseEvernodeClient+extractEvernodeEvent) +**Returns**: The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction object to be deserialized and extracted. | + + + +### tenantClient.getHostInfo(hostAddress) ⇒ +Get the registered host information. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getHostInfo](#BaseEvernodeClient+getHostInfo) +**Returns**: The registered host information object. Returns null if not registered. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the host. | + + + +### tenantClient.getAllHostsFromLedger() ⇒ +Get the hosts registered in Evernode. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getAllHostsFromLedger](#BaseEvernodeClient+getAllHostsFromLedger) +**Returns**: The list of hosts. + + +### tenantClient.getAllCandidatesFromLedger() ⇒ +Get the governor in Evernode. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getAllCandidatesFromLedger](#BaseEvernodeClient+getAllCandidatesFromLedger) +**Returns**: The list of candidates. + + +### tenantClient.pruneDeadHost(hostAddress) +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. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [pruneDeadHost](#BaseEvernodeClient+pruneDeadHost) + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to be pruned. | + + + +### tenantClient.getCandidateByOwner(ownerAddress) ⇒ +Get proposed new hook candidate info. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getCandidateByOwner](#BaseEvernodeClient+getCandidateByOwner) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | [Optional] Address of the owner. | + + + +### tenantClient.getDudHostCandidatesByOwner(ownerAddress) ⇒ +Get proposed dud host candidates. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getDudHostCandidatesByOwner](#BaseEvernodeClient+getDudHostCandidatesByOwner) +**Returns**: An array of candidate information. Returns empty array if no candidates. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | | Address of the owner | + + + +### tenantClient.getCandidateById(candidateId) ⇒ +Get candidate info. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getCandidateById](#BaseEvernodeClient+getCandidateById) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate. | + + + +### tenantClient.getDudHostVoteInfo(hostAddress) ⇒ +Get reported dud host info. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getDudHostVoteInfo](#BaseEvernodeClient+getDudHostVoteInfo) +**Returns**: The dud host candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the dud host. | + + + +### tenantClient.getPilotedModeVoteInfo() ⇒ +Get piloted mode vote info. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getPilotedModeVoteInfo](#BaseEvernodeClient+getPilotedModeVoteInfo) +**Returns**: The piloted mode candidate information. Returns null if no candidate. + + +### tenantClient.getReputationAddressByOrderedId(orderedId, moment) ⇒ +Get reputation order info of given orderedId. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getReputationAddressByOrderedId](#BaseEvernodeClient+getReputationAddressByOrderedId) +**Returns**: Reputation address info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| orderedId | number | | Order id of the host. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### tenantClient.getReputationOrderByAddress(hostAddress, moment) ⇒ +Get reputation order info of given host. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getReputationOrderByAddress](#BaseEvernodeClient+getReputationOrderByAddress) +**Returns**: Reputation order info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | (optional) Host address. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### tenantClient.getReputationContractInfoByAddress(hostsAddress, moment) ⇒ +Get reputation contract info of given host. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getReputationContractInfoByAddress](#BaseEvernodeClient+getReputationContractInfoByAddress) +**Returns**: Reputation contract info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | +| moment | number | (optional) Moment to get reputation contract info for. | + + + +### tenantClient.getReputationInfoByAddress(hostsAddress) ⇒ +Get reputation info of given host. + +**Kind**: instance method of [TenantClient](#TenantClient) +**Overrides**: [getReputationInfoByAddress](#BaseEvernodeClient+getReputationInfoByAddress) +**Returns**: Reputation info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | + + + +## Defaults +Defaults class is responsible for retrieving and overriding the default Evernode network configurations. + +**Kind**: global class + +* [Defaults](#Defaults) + * [.values](#Defaults.values) ⇒ + * [.useNetwork(network)](#Defaults.useNetwork) + * [.set(newDefaults)](#Defaults.set) + + + +### Defaults.values ⇒ +Read Evernode default configs. + +**Kind**: static property of [Defaults](#Defaults) +**Returns**: The Object of Evernode configs + + +### Defaults.useNetwork(network) +Load defaults from the public definitions json. + +**Kind**: static method of [Defaults](#Defaults) + +| Param | Type | Description | +| --- | --- | --- | +| network | string | Network to choose the info. | + + + +### Defaults.set(newDefaults) +Override Evernode default configs. + +**Kind**: static method of [Defaults](#Defaults) + +| Param | Type | Description | +| --- | --- | --- | +| newDefaults | object | 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' }` | + + + +## EncryptionHelper +EncryptionHelper class is responsible for encrypt and decrypt functions for messages. + +**Kind**: global class + +* [EncryptionHelper](#EncryptionHelper) + * [.encrypt(publicKey, message, [options])](#EncryptionHelper.encrypt) ⇒ Promise.<(string\|null)> + * [.decrypt(privateKey, encrypted)](#EncryptionHelper.decrypt) ⇒ Promise.<(Object\|null)> + + + +### EncryptionHelper.encrypt(publicKey, message, [options]) ⇒ Promise.<(string\|null)> +Encrypts a message using the given public key. + +**Kind**: static method of [EncryptionHelper](#EncryptionHelper) +**Returns**: Promise.<(string\|null)> - A promise that resolves to the encrypted message in base64 format, or null if encryption fails. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| publicKey | string | | The public key to use for encryption. | +| message | Object | | The message object to be encrypted. | +| [options] | Object | {} | Optional encryption parameters. | + + + +### EncryptionHelper.decrypt(privateKey, encrypted) ⇒ Promise.<(Object\|null)> +Decrypts an encrypted message using the given private key. + +**Kind**: static method of [EncryptionHelper](#EncryptionHelper) +**Returns**: Promise.<(Object\|null)> - A promise that resolves to the decrypted message as an object, or null if decryption fails. + +| Param | Type | Description | +| --- | --- | --- | +| privateKey | string | The private key to use for decryption. | +| encrypted | string | The encrypted message string. | + + + +## EvernodeHelpers +Provides various utility functions for working with leases, tokens, and ledger entries within the Xahau ecosystem. + +**Kind**: global class + +* [EvernodeHelpers](#EvernodeHelpers) + * [.getLeases(xrplAcc)](#EvernodeHelpers.getLeases) ⇒ Promise.<Array.<Object>> + * [.getLeaseByIndex(xrplApi, index)](#EvernodeHelpers.getLeaseByIndex) ⇒ Promise.<(Object\|null)> + * [.getLeaseOffers(xrplAcc)](#EvernodeHelpers.getLeaseOffers) ⇒ Promise.<Array.<Object>> + * [.getUnofferedLeases(xrplAcc)](#EvernodeHelpers.getUnofferedLeases) ⇒ Promise.<Array.<Object>> + * [.getNFTPageAndLocation(nfTokenId, xrplAcc, xrplApi, [buffer])](#EvernodeHelpers.getNFTPageAndLocation) ⇒ Promise.<(Buffer\|Object)> + * [.getEpochRewardQuota(epoch, firstEpochRewardQuota)](#EvernodeHelpers.getEpochRewardQuota) ⇒ number + * [.isValidURI(uri, pattern, [tokenCategory])](#EvernodeHelpers.isValidURI) ⇒ boolean + + + +### EvernodeHelpers.getLeases(xrplAcc) ⇒ Promise.<Array.<Object>> +Retrieves URI tokens that are valid leases for the specified XRPL account. + +**Kind**: static method of [EvernodeHelpers](#EvernodeHelpers) +**Returns**: Promise.<Array.<Object>> - A promise that resolves to an array of URI tokens that are valid leases. + +| Param | Type | Description | +| --- | --- | --- | +| xrplAcc | Object | The XRPL account object. | + + + +### EvernodeHelpers.getLeaseByIndex(xrplApi, index) ⇒ Promise.<(Object\|null)> +Retrieves a lease by its index from the XRPL ledger. + +**Kind**: static method of [EvernodeHelpers](#EvernodeHelpers) +**Returns**: Promise.<(Object\|null)> - A promise that resolves to the lease entry or null if not found or invalid. + +| Param | Type | Description | +| --- | --- | --- | +| xrplApi | [XrplApi](#XrplApi) | The XRPL API object. | +| index | string | The ledger entry index. | + + + +### EvernodeHelpers.getLeaseOffers(xrplAcc) ⇒ Promise.<Array.<Object>> +Retrieves all leases that have offers (i.e., an associated amount) for the specified XRPL account. + +**Kind**: static method of [EvernodeHelpers](#EvernodeHelpers) +**Returns**: Promise.<Array.<Object>> - A promise that resolves to an array of URI tokens with offers. + +| Param | Type | Description | +| --- | --- | --- | +| xrplAcc | Object | The XRPL account object. | + + + +### EvernodeHelpers.getUnofferedLeases(xrplAcc) ⇒ Promise.<Array.<Object>> +Retrieves leases that do not have offers (i.e., no amount associated) for the specified XRPL account. + +**Kind**: static method of [EvernodeHelpers](#EvernodeHelpers) +**Returns**: Promise.<Array.<Object>> - A promise that resolves to an array of unoffered URI tokens. + +| Param | Type | Description | +| --- | --- | --- | +| xrplAcc | Object | The XRPL account object. | + + + +### EvernodeHelpers.getNFTPageAndLocation(nfTokenId, xrplAcc, xrplApi, [buffer]) ⇒ Promise.<(Buffer\|Object)> +Finds the NFT page and location of a specific NFToken in the XRPL ledger. + +**Kind**: static method of [EvernodeHelpers](#EvernodeHelpers) +**Returns**: Promise.<(Buffer\|Object)> - A promise that resolves to either a buffer with the NFT page and location or an object with page and location details. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| nfTokenId | string | | The ID of the NFToken. | +| xrplAcc | Object | | The XRPL account object. | +| xrplApi | Object | | The XRPL API object. | +| [buffer] | boolean | true | Whether to return the result as a buffer. | + + + +### EvernodeHelpers.getEpochRewardQuota(epoch, firstEpochRewardQuota) ⇒ number +Calculates the reward quota for a specific epoch. + +**Kind**: static method of [EvernodeHelpers](#EvernodeHelpers) +**Returns**: number - The calculated reward quota for the specified epoch. + +| Param | Type | Description | +| --- | --- | --- | +| epoch | number | The epoch number. | +| firstEpochRewardQuota | number | The reward quota for the first epoch. | + + + +### EvernodeHelpers.isValidURI(uri, pattern, [tokenCategory]) ⇒ boolean +Checks if a given URI is valid based on a pattern and token category. + +**Kind**: static method of [EvernodeHelpers](#EvernodeHelpers) +**Returns**: boolean - Returns true if the URI is valid, false otherwise. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uri | string | | The URI to validate. | +| pattern | string | | The pattern to match the URI against. | +| [tokenCategory] | string | "URITokenTypes.LEASE_URI_TOKEN" | The token category (default is a lease URI token). | + + + +## StateHelpers +Provides various utility functions for working with States. + +**Kind**: global class + +* [StateHelpers](#StateHelpers) + * [.getStateData(states, key)](#StateHelpers.getStateData) ⇒ Object \| null + * [.decodeReputationHostAddressState(stateKeyBuf, stateDataBuf)](#StateHelpers.decodeReputationHostAddressState) ⇒ Object + * [.decodeReputationHostOrderAddressState(stateKeyBuf, stateDataBuf)](#StateHelpers.decodeReputationHostOrderAddressState) ⇒ Object + * [.decodeReputationHostOrderedIdState(stateKeyBuf, stateDataBuf)](#StateHelpers.decodeReputationHostOrderedIdState) ⇒ Object + * [.decodeReputationHostCountState(stateKeyBuf, stateDataBuf)](#StateHelpers.decodeReputationHostCountState) ⇒ Object + * [.decodeHostAddressState(stateKeyBuf, stateDataBuf)](#StateHelpers.decodeHostAddressState) ⇒ Object + * [.decodeTokenIdState(stateDataBuf)](#StateHelpers.decodeTokenIdState) ⇒ Object + * [.decodeTransfereeAddrState(stateKeyBuf, stateDataBuf)](#StateHelpers.decodeTransfereeAddrState) ⇒ Object + * [.decodeCandidateOwnerState(stateKeyBuf, stateDataBuf)](#StateHelpers.decodeCandidateOwnerState) ⇒ Object + * [.decodeCandidateIdState(stateDataBuf)](#StateHelpers.decodeCandidateIdState) ⇒ Object + * [.decodeStateData(stateKey, stateData)](#StateHelpers.decodeStateData) ⇒ Object + * [.decodeStateKey(stateKey)](#StateHelpers.decodeStateKey) ⇒ Object + * [.generateTokenIdStateKey(uriToken)](#StateHelpers.generateTokenIdStateKey) ⇒ string + * [.generateHostAddrStateKey(address)](#StateHelpers.generateHostAddrStateKey) ⇒ string + * [.generateReputationHostAddrStateKey(address)](#StateHelpers.generateReputationHostAddrStateKey) ⇒ string + * [.generateReputationHostOrderAddressStateKey(address, moment)](#StateHelpers.generateReputationHostOrderAddressStateKey) ⇒ string + * [.generateReputationHostOrderedIdStateKey(orderedId, moment)](#StateHelpers.generateReputationHostOrderedIdStateKey) ⇒ string + * [.generateReputationHostCountStateKey(moment)](#StateHelpers.generateReputationHostCountStateKey) ⇒ string + * [.generateReputationContractInfoStateKey(address)](#StateHelpers.generateReputationContractInfoStateKey) ⇒ string + * [.generateTransfereeAddrStateKey(address)](#StateHelpers.generateTransfereeAddrStateKey) ⇒ string + * [.generateCandidateIdStateKey(uniqueId)](#StateHelpers.generateCandidateIdStateKey) ⇒ string + * [.generateCandidateOwnerStateKey(owner)](#StateHelpers.generateCandidateOwnerStateKey) ⇒ string + * [.getHookStateIndex(hookAccount, stateKey, [hookNamespace])](#StateHelpers.getHookStateIndex) ⇒ string + * [.getNewHookCandidateId(hashesBuf)](#StateHelpers.getNewHookCandidateId) ⇒ string + * [.getPilotedModeCandidateId()](#StateHelpers.getPilotedModeCandidateId) ⇒ string + * [.getDudHostCandidateId(hostAddress)](#StateHelpers.getDudHostCandidateId) ⇒ string + * [.getCandidateType(candidateId)](#StateHelpers.getCandidateType) ⇒ number + + + +### StateHelpers.getStateData(states, key) ⇒ Object \| null +Retrieves the state data for a specific key from an array of states. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object \| null - The state data or null if not found. + +| Param | Type | Description | +| --- | --- | --- | +| states | Array | Array of state objects. | +| key | string | Key for the state data. | + + + +### StateHelpers.decodeReputationHostAddressState(stateKeyBuf, stateDataBuf) ⇒ Object +Decodes reputation host address state from buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - Decoded state data including host address and reputation metrics. + +| Param | Type | Description | +| --- | --- | --- | +| stateKeyBuf | Buffer | Buffer containing the state key. | +| stateDataBuf | Buffer | Buffer containing the state data. | + + + +### StateHelpers.decodeReputationHostOrderAddressState(stateKeyBuf, stateDataBuf) ⇒ Object +Decodes reputation host order address state from buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - Decoded state data including moment and ordered ID. + +| Param | Type | Description | +| --- | --- | --- | +| stateKeyBuf | Buffer | Buffer containing the state key. | +| stateDataBuf | Buffer | Buffer containing the state data. | + + + +### StateHelpers.decodeReputationHostOrderedIdState(stateKeyBuf, stateDataBuf) ⇒ Object +Decodes reputation host ordered ID state from buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - Decoded state data including moment and ordered ID. + +| Param | Type | Description | +| --- | --- | --- | +| stateKeyBuf | Buffer | Buffer containing the state key. | +| stateDataBuf | Buffer | Buffer containing the state data. | + + + +### StateHelpers.decodeReputationHostCountState(stateKeyBuf, stateDataBuf) ⇒ Object +Decodes reputation host count state from buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - Decoded state data including moment and count. + +| Param | Type | Description | +| --- | --- | --- | +| stateKeyBuf | Buffer | Buffer containing the state key. | +| stateDataBuf | Buffer | Buffer containing the state data. | + + + +### StateHelpers.decodeHostAddressState(stateKeyBuf, stateDataBuf) ⇒ Object +Decodes a host address state from buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - The decoded host address state. + +| Param | Type | Description | +| --- | --- | --- | +| stateKeyBuf | Buffer | The buffer containing the state key. | +| stateDataBuf | Buffer | The buffer containing the state data. | + + + +### StateHelpers.decodeTokenIdState(stateDataBuf) ⇒ Object +Decodes a token ID state from a buffer. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - The decoded token ID state. + +| Param | Type | Description | +| --- | --- | --- | +| stateDataBuf | Buffer | The buffer containing the state data. | + + + +### StateHelpers.decodeTransfereeAddrState(stateKeyBuf, stateDataBuf) ⇒ Object +Decodes a transferee address state from buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - The decoded transferee address state. + +| Param | Type | Description | +| --- | --- | --- | +| stateKeyBuf | Buffer | The buffer containing the state key. | +| stateDataBuf | Buffer | The buffer containing the state data. | + + + +### StateHelpers.decodeCandidateOwnerState(stateKeyBuf, stateDataBuf) ⇒ Object +Decodes a candidate owner state from buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - The decoded candidate owner state. + +| Param | Type | Description | +| --- | --- | --- | +| stateKeyBuf | Buffer | The buffer containing the state key. | +| stateDataBuf | Buffer | The buffer containing the state data. | + + + +### StateHelpers.decodeCandidateIdState(stateDataBuf) ⇒ Object +Decodes a candidate ID state from a buffer. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - The decoded candidate ID state. + +| Param | Type | Description | +| --- | --- | --- | +| stateDataBuf | Buffer | The buffer containing the state data. | + + + +### StateHelpers.decodeStateData(stateKey, stateData) ⇒ Object +Decodes state data based on the state key and state data buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - The decoded state data with type information. + +| Param | Type | Description | +| --- | --- | --- | +| stateKey | Buffer | The buffer containing the state key. | +| stateData | Buffer | The buffer containing the state data. | + + + +### StateHelpers.decodeStateKey(stateKey) ⇒ Object +Decodes a state key into a type and key. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: Object - An object containing the key as a hexadecimal string and its type. +**Throws**: + +- Object Throws a Validation Error if the state key is invalid. + + +| Param | Type | Description | +| --- | --- | --- | +| stateKey | Buffer | The buffer containing the state key. | + + + +### StateHelpers.generateTokenIdStateKey(uriToken) ⇒ string +Generates a state key for a token ID. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| uriToken | string | The URI token in hexadecimal format. | + + + +### StateHelpers.generateHostAddrStateKey(address) ⇒ string +Generates a state key for a host address. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The host address. | + + + +### StateHelpers.generateReputationHostAddrStateKey(address) ⇒ string +Generates a state key for a reputation host address. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The reputation host address. | + + + +### StateHelpers.generateReputationHostOrderAddressStateKey(address, moment) ⇒ string +Generates a state key for a reputation host order address. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The reputation host address. | +| moment | number | The moment timestamp. | + + + +### StateHelpers.generateReputationHostOrderedIdStateKey(orderedId, moment) ⇒ string +Generates a state key for a reputation host ordered ID. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| orderedId | string | The ordered ID. | +| moment | number | The moment timestamp. | + + + +### StateHelpers.generateReputationHostCountStateKey(moment) ⇒ string +Generates a state key for a reputation host count. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| moment | number | The moment timestamp. | + + + +### StateHelpers.generateReputationContractInfoStateKey(address) ⇒ string +Generates a state key for reputation contract information. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The contract address. | + + + +### StateHelpers.generateTransfereeAddrStateKey(address) ⇒ string +Generates a state key for a transferee address. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The transferee address. | + + + +### StateHelpers.generateCandidateIdStateKey(uniqueId) ⇒ string +Generates a state key for a candidate ID. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| uniqueId | string | The unique candidate ID. | + + + +### StateHelpers.generateCandidateOwnerStateKey(owner) ⇒ string +Generates a state key for a candidate owner. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated state key as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| owner | string | The candidate owner address. | + + + +### StateHelpers.getHookStateIndex(hookAccount, stateKey, [hookNamespace]) ⇒ string +Gets the hook state index for a specific hook account and state key. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The hook state index as a hexadecimal string. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hookAccount | string | | The hook account address. | +| stateKey | string | | The state key as a hexadecimal string. | +| [hookNamespace] | string | "EvernodeConstants.HOOK_NAMESPACE" | The hook namespace. | + + + +### StateHelpers.getNewHookCandidateId(hashesBuf) ⇒ string +Generates a new hook candidate ID based on hash buffers. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated candidate ID as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| hashesBuf | Buffer | The buffer containing the hash data. | + + + +### StateHelpers.getPilotedModeCandidateId() ⇒ string +Generates a candidate ID for the piloted mode. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated candidate ID as a hexadecimal string. + + +### StateHelpers.getDudHostCandidateId(hostAddress) ⇒ string +Generates a candidate ID for a dud host. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: string - The generated candidate ID as a hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | The host address. | + + + +### StateHelpers.getCandidateType(candidateId) ⇒ number +Retrieves the candidate type from a candidate ID. + +**Kind**: static method of [StateHelpers](#StateHelpers) +**Returns**: number - The candidate type. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | The candidate ID as a hexadecimal string. | + + + +## TransactionHelper +Provides various utility functions for working with Xahau Transactions. + +**Kind**: global class + +* [TransactionHelper](#TransactionHelper) + * [.formatMemos(memos)](#TransactionHelper.formatMemos) ⇒ Array.<Object> + * [.deserializeMemos(memos)](#TransactionHelper.deserializeMemos) ⇒ Array.<Object> + * [.formatHookParams(params)](#TransactionHelper.formatHookParams) ⇒ Array.<Object> + * [.deserializeHookParams(params)](#TransactionHelper.deserializeHookParams) ⇒ Array.<Object> + * [.hexToASCII(hex)](#TransactionHelper.hexToASCII) ⇒ string + * [.asciiToHex(str)](#TransactionHelper.asciiToHex) ⇒ string + + + +### TransactionHelper.formatMemos(memos) ⇒ Array.<Object> +Converts an array of memos from the internal format to the XRPL library format. + +**Kind**: static method of [TransactionHelper](#TransactionHelper) +**Returns**: Array.<Object> - An array of memo objects in the XRPL library format. + +| Param | Type | Description | +| --- | --- | --- | +| memos | Array.<Object> | An array of memo objects in the internal format. | + + + +### TransactionHelper.deserializeMemos(memos) ⇒ Array.<Object> +Converts an array of memos from the XRPL library format to the internal format. + +**Kind**: static method of [TransactionHelper](#TransactionHelper) +**Returns**: Array.<Object> - An array of memo objects in the internal format. + +| Param | Type | Description | +| --- | --- | --- | +| memos | Array.<Object> | An array of memo objects in the XRPL library format. | + + + +### TransactionHelper.formatHookParams(params) ⇒ Array.<Object> +Converts an array of hook parameters from the internal format to the XRPL library format. + +**Kind**: static method of [TransactionHelper](#TransactionHelper) +**Returns**: Array.<Object> - An array of hook parameter objects in the XRPL library format. + +| Param | Type | Description | +| --- | --- | --- | +| params | Array.<Object> | An array of hook parameter objects in the internal format. | + + + +### TransactionHelper.deserializeHookParams(params) ⇒ Array.<Object> +Converts an array of hook parameters from the XRPL library format to the internal format. + +**Kind**: static method of [TransactionHelper](#TransactionHelper) +**Returns**: Array.<Object> - An array of hook parameter objects in the internal format. + +| Param | Type | Description | +| --- | --- | --- | +| params | Array.<Object> | An array of hook parameter objects in the XRPL library format. | + + + +### TransactionHelper.hexToASCII(hex) ⇒ string +Converts a hexadecimal string to an ASCII string. + +**Kind**: static method of [TransactionHelper](#TransactionHelper) +**Returns**: string - The resulting ASCII string. + +| Param | Type | Description | +| --- | --- | --- | +| hex | string | The hexadecimal string to be converted. | + + + +### TransactionHelper.asciiToHex(str) ⇒ string +Converts an ASCII string to a hexadecimal string. + +**Kind**: static method of [TransactionHelper](#TransactionHelper) +**Returns**: string - The resulting hexadecimal string. + +| Param | Type | Description | +| --- | --- | --- | +| str | string | The ASCII string to be converted. | + + + +## UtilHelpers +Provides utility helper functions for various operations. + +**Kind**: global class + +* [UtilHelpers](#UtilHelpers) + * [.decodeLeaseTokenUri(hexUri)](#UtilHelpers.decodeLeaseTokenUri) ⇒ Object + * [.getCurrentUnixTime([format])](#UtilHelpers.getCurrentUnixTime) ⇒ number + * [.deriveKeypair(secret)](#UtilHelpers.deriveKeypair) ⇒ Object + * [.deriveAddress(publicKey)](#UtilHelpers.deriveAddress) ⇒ string + + + +### UtilHelpers.decodeLeaseTokenUri(hexUri) ⇒ Object +Decodes a lease token URI into its integrant parts. + +**Kind**: static method of [UtilHelpers](#UtilHelpers) +**Returns**: Object - An object containing the decoded lease token URI's version, leaseIndex, halfTos, leaseAmount, identifier, and outboundIP + +| Param | Type | Description | +| --- | --- | --- | +| hexUri | string | The lease token URI in hexadecimal format. | + + + +### UtilHelpers.getCurrentUnixTime([format]) ⇒ number +Gets the current Unix time. + +**Kind**: static method of [UtilHelpers](#UtilHelpers) +**Returns**: number - The current Unix time in the specified format. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [format] | string | "\"sec\"" | The format of the time. If "sec", returns the time in seconds; otherwise, returns the time in milliseconds. | + + + +### UtilHelpers.deriveKeypair(secret) ⇒ Object +Derives a keypair from a given secret. + +**Kind**: static method of [UtilHelpers](#UtilHelpers) +**Returns**: Object - An object containing the derived keypair. + +| Param | Type | Description | +| --- | --- | --- | +| secret | string | The secret used to derive the keypair. | + + + +### UtilHelpers.deriveAddress(publicKey) ⇒ string +Derives an address from a given public key. + +**Kind**: static method of [UtilHelpers](#UtilHelpers) +**Returns**: string - The derived address. + +| Param | Type | Description | +| --- | --- | --- | +| publicKey | string | The public key used to derive the address. | + + + +## XflHelpers +Helper class for handling XFL (Extended Floating-Point) float numbers. + +**Kind**: global class + +* [XflHelpers](#XflHelpers) + * [.getExponent(xfl)](#XflHelpers.getExponent) ⇒ bigint + * [.getMantissa(xfl)](#XflHelpers.getMantissa) ⇒ bigint + * [.isNegative(xfl)](#XflHelpers.isNegative) ⇒ boolean + * [.toString(xfl)](#XflHelpers.toString) ⇒ string + * [.getXfl(floatStr)](#XflHelpers.getXfl) ⇒ bigint + + + +### XflHelpers.getExponent(xfl) ⇒ bigint +Retrieves the exponent of the XFL float number. + +**Kind**: static method of [XflHelpers](#XflHelpers) +**Returns**: bigint - The exponent of the XFL float number. +**Throws**: + +- string Throws an error if the XFL float number is negative. + + +| Param | Type | Description | +| --- | --- | --- | +| xfl | bigint | The XFL float number. | + + + +### XflHelpers.getMantissa(xfl) ⇒ bigint +Retrieves the mantissa of the XFL float number. + +**Kind**: static method of [XflHelpers](#XflHelpers) +**Returns**: bigint - The mantissa of the XFL float number. +**Throws**: + +- string Throws an error if the XFL float number is negative. + + +| Param | Type | Description | +| --- | --- | --- | +| xfl | bigint | The XFL float number. | + + + +### XflHelpers.isNegative(xfl) ⇒ boolean +Checks if the XFL float number is negative. + +**Kind**: static method of [XflHelpers](#XflHelpers) +**Returns**: boolean - `true` if the XFL float number is negative, otherwise `false`. +**Throws**: + +- string Throws an error if the XFL float number is negative. + + +| Param | Type | Description | +| --- | --- | --- | +| xfl | bigint | The XFL float number. | + + + +### XflHelpers.toString(xfl) ⇒ string +Converts an XFL float number to its string representation. + +**Kind**: static method of [XflHelpers](#XflHelpers) +**Returns**: string - The string representation of the XFL float number. +**Throws**: + +- string Throws an error if the XFL float number is negative. + + +| Param | Type | Description | +| --- | --- | --- | +| xfl | bigint | The XFL float number. | + + + +### XflHelpers.getXfl(floatStr) ⇒ bigint +Converts a string representation of a float number to an XFL float number. + +**Kind**: static method of [XflHelpers](#XflHelpers) +**Returns**: bigint - The XFL float number. + +| Param | Type | Description | +| --- | --- | --- | +| floatStr | string | The string representation of the float number. | + + + +## XrplAccount +Represents an XRP Ledger account and provides methods for account management. + +**Kind**: global class + +* [XrplAccount](#XrplAccount) + * [new XrplAccount(address, secret, options)](#new_XrplAccount_new) + * [.on(event, handler)](#XrplAccount+on) + * [.once(event, handler)](#XrplAccount+once) + * [.off(event, handler)](#XrplAccount+off) + * [.deriveKeypair()](#XrplAccount+deriveKeypair) ⇒ Object + * [.exists()](#XrplAccount+exists) ⇒ Promise.<boolean> + * [.getInfo()](#XrplAccount+getInfo) ⇒ Promise.<Object> + * [.getSequence()](#XrplAccount+getSequence) ⇒ Promise.<number> + * [.getMintedNFTokens()](#XrplAccount+getMintedNFTokens) ⇒ Promise.<number> + * [.getBurnedNFTokens()](#XrplAccount+getBurnedNFTokens) ⇒ number + * [.getMessageKey()](#XrplAccount+getMessageKey) ⇒ Promise.<(string\|null)> + * [.getWalletLocator()](#XrplAccount+getWalletLocator) ⇒ Promise.<(string\|null)> + * [.getDomain()](#XrplAccount+getDomain) ⇒ Promise.<(string\|null)> + * [.getTrustLines([currency], issuer)](#XrplAccount+getTrustLines) ⇒ Promise.<Array.<Object>> + * [.getChecks(fromAccount)](#XrplAccount+getChecks) ⇒ Promise.<Array.<Object>> + * [.getNfts()](#XrplAccount+getNfts) ⇒ Promise.<Array.<Object>> + * [.getOffers()](#XrplAccount+getOffers) ⇒ Promise.<Array.<Object>> + * [.getNftOffers()](#XrplAccount+getNftOffers) ⇒ Promise.<Array.<Object>> + * [.getNftByUri(uri, [isHexUri])](#XrplAccount+getNftByUri) ⇒ Promise.<(Object\|null)> + * [.getAccountObjects(options)](#XrplAccount+getAccountObjects) ⇒ Promise.<Array.<Object>> + * [.getNamespaceEntries(namespaceId, [options])](#XrplAccount+getNamespaceEntries) ⇒ Promise.<Array.<Object>> + * [.getFlags()](#XrplAccount+getFlags) ⇒ Promise.<Object> + * [.getAccountTrx([minLedgerIndex], [maxLedgerIndex], [isForward])](#XrplAccount+getAccountTrx) ⇒ Promise.<Array> + * [.hasValidKeyPair()](#XrplAccount+hasValidKeyPair) ⇒ Promise.<boolean> + * [.setAccountFields(fields, options)](#XrplAccount+setAccountFields) ⇒ Promise.<Object> + * [.prepareSetAccountFields(fields, [options])](#XrplAccount+prepareSetAccountFields) ⇒ Promise.<Object> + * [.setSignerList(signerList, [options])](#XrplAccount+setSignerList) ⇒ Promise.<Object> + * [.prepareSetSignerList(signerList, options)](#XrplAccount+prepareSetSignerList) ⇒ Promise.<Object> + * [.invoke(toAddr, [blobObj], [options])](#XrplAccount+invoke) ⇒ Promise.<Object> + * [.prepareInvoke(toAddr, [blobObj], [options])](#XrplAccount+prepareInvoke) ⇒ Promise.<Object> + * [.makePayment(toAddr, amount, [currency], [issuer], [memos], [options])](#XrplAccount+makePayment) ⇒ Promise.<Object> + * [.prepareMakePayment(toAddr, amount, [currency], [issuer], [memos], [options])](#XrplAccount+prepareMakePayment) ⇒ Promise.<Object> + * [.setTrustLine(currency, issuer, limit, [allowRippling], [memos], [options])](#XrplAccount+setTrustLine) ⇒ Promise.<Object> + * [.prepareSetTrustLine(currency, issuer, limit, [allowRippling], [memos], [options])](#XrplAccount+prepareSetTrustLine) ⇒ Promise.<Object> + * [.setRegularKey(regularKey, [memos], [options])](#XrplAccount+setRegularKey) ⇒ Promise.<Object> + * [.prepareSetRegularKey(regularKey, [memos], [options])](#XrplAccount+prepareSetRegularKey) ⇒ Promise.<Object> + * [.prepareCashCheck(check, [options])](#XrplAccount+prepareCashCheck) ⇒ Promise.<Object> + * [.offerSell(sellAmount, sellCurrency, sellIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options])](#XrplAccount+offerSell) ⇒ Promise.<Object> + * [.prepareOfferSell(sellAmount, sellCurrency, sellIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options])](#XrplAccount+prepareOfferSell) ⇒ Promise.<Object> + * [.offerBuy(buyAmount, buyCurrency, buyIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options])](#XrplAccount+offerBuy) ⇒ Promise.<Object> + * [.prepareOfferBuy(buyAmount, buyCurrency, buyIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options])](#XrplAccount+prepareOfferBuy) ⇒ Promise.<Object> + * [.cancelOffer(offerSequence, [memos], [options])](#XrplAccount+cancelOffer) ⇒ Promise.<Object> + * [.prepareCancelOffer(offerSequence, [memos], [options])](#XrplAccount+prepareCancelOffer) ⇒ Promise.<Object> + * [.subscribe()](#XrplAccount+subscribe) ⇒ Promise.<void> + * [.unsubscribe()](#XrplAccount+unsubscribe) ⇒ Promise.<void> + * [.submitTransactionBlob(txBlob)](#XrplAccount+submitTransactionBlob) ⇒ Promise.<Object> + * [.sign(tx, [isMultiSign])](#XrplAccount+sign) ⇒ Object + * [.mintURIToken(uri, [digest], [flags], [options])](#XrplAccount+mintURIToken) ⇒ Promise.<Object> + * [.prepareMintURIToken(uri, [digest], [flags], [options])](#XrplAccount+prepareMintURIToken) ⇒ Promise.<Object> + * [.burnURIToken(uriTokenID, [options])](#XrplAccount+burnURIToken) ⇒ Promise.<Object> + * [.prepareBurnURIToken(uriTokenID, [options])](#XrplAccount+prepareBurnURIToken) ⇒ Promise.<Object> + * [.sellURIToken(uriTokenID, amount, currency, [issuer], [toAddr], [memos], [options])](#XrplAccount+sellURIToken) ⇒ Promise.<Object> + * [.prepareSellURIToken(uriTokenID, amount, currency, [issuer], [toAddr], [memos], [options])](#XrplAccount+prepareSellURIToken) ⇒ Promise.<Object> + * [.buyURIToken(uriToken, [memos], [options])](#XrplAccount+buyURIToken) ⇒ Promise.<Object> + * [.prepareBuyURIToken(uriToken, [memos], [options])](#XrplAccount+prepareBuyURIToken) ⇒ Promise.<Object> + * [.clearURITokenOffer(uriTokenID, [options])](#XrplAccount+clearURITokenOffer) ⇒ Promise.<Object> + * [.prepareClearURITokenOffer(uriTokenID, [options])](#XrplAccount+prepareClearURITokenOffer) ⇒ Promise.<Object> + * [.getURITokens(options)](#XrplAccount+getURITokens) ⇒ Promise.<Array> + * [.getURITokenByUri(uri, [isHexUri])](#XrplAccount+getURITokenByUri) ⇒ Promise.<Object> + * [.generateIssuedURITokenId(uri, [isHexUri])](#XrplAccount+generateIssuedURITokenId) ⇒ string + * [.signAndSubmit(preparedTransaction, submissionRef)](#XrplAccount+signAndSubmit) ⇒ Promise.<Object> + * [.submitMultisigned(tx)](#XrplAccount+submitMultisigned) ⇒ Promise.<Object> + + + +### new XrplAccount(address, secret, options) +Constructs an XrplAccount instance. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string \| null | null | The account address (optional). | +| secret | string \| null | null | The secret key (optional). | +| options | Object | | Additional options (optional). | + + + +### xrplAccount.on(event, handler) +Adds an event listener for the specified event. + +**Kind**: instance method of [XrplAccount](#XrplAccount) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event. | +| handler | function | The event handler function. | + + + +### xrplAccount.once(event, handler) +Adds a one-time event listener for the specified event. + +**Kind**: instance method of [XrplAccount](#XrplAccount) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event. | +| handler | function | The event handler function. | + + + +### xrplAccount.off(event, handler) +Removes an event listener for the specified event. + +**Kind**: instance method of [XrplAccount](#XrplAccount) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | The name of the event. | +| handler | function \| null | | The event handler function (optional). | + + + +### xrplAccount.deriveKeypair() ⇒ Object +Derives the keypair from the account secret. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Object - The derived keypair. +**Throws**: + +- Will throw an error if the account secret is empty. + + + +### xrplAccount.exists() ⇒ Promise.<boolean> +Checks if the account exists. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<boolean> - True if the account exists, otherwise false. + + +### xrplAccount.getInfo() ⇒ Promise.<Object> +Retrieves account information. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The account information. + + +### xrplAccount.getSequence() ⇒ Promise.<number> +Gets the account's sequence number. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<number> - The account's sequence number. + + +### xrplAccount.getMintedNFTokens() ⇒ Promise.<number> +Retrieves the number of NFTs minted by the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<number> - The number of minted NFTs. + + +### xrplAccount.getBurnedNFTokens() ⇒ number +Retrieves the number of NFTs burned by the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: number - The number of burned NFTs. + + +### xrplAccount.getMessageKey() ⇒ Promise.<(string\|null)> +Retrieves the account's message key. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<(string\|null)> - The message key or null if not set. + + +### xrplAccount.getWalletLocator() ⇒ Promise.<(string\|null)> +Retrieves the wallet locator from the account info. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<(string\|null)> - The wallet locator or null if not found. + + +### xrplAccount.getDomain() ⇒ Promise.<(string\|null)> +Retrieves the domain from the account info and converts it from hex to ASCII. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<(string\|null)> - The domain as ASCII or null if not found. + + +### xrplAccount.getTrustLines([currency], issuer) ⇒ Promise.<Array.<Object>> +Retrieves the trust lines for the account, filtered by currency and issuer. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array.<Object>> - The list of trust lines, filtered if a currency is specified. + +| Param | Type | Description | +| --- | --- | --- | +| [currency] | string | The currency to filter by. | +| issuer | string | The issuer of the trust lines. | + + + +### xrplAccount.getChecks(fromAccount) ⇒ Promise.<Array.<Object>> +Retrieves the checks for the specified account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array.<Object>> - The list of checks. + +| Param | Type | Description | +| --- | --- | --- | +| fromAccount | string | The account from which to retrieve checks. | + + + +### xrplAccount.getNfts() ⇒ Promise.<Array.<Object>> +Retrieves the NFTs for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array.<Object>> - The list of NFTs. + + +### xrplAccount.getOffers() ⇒ Promise.<Array.<Object>> +Retrieves the offers for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array.<Object>> - The list of offers. + + +### xrplAccount.getNftOffers() ⇒ Promise.<Array.<Object>> +Retrieves the NFT offers for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array.<Object>> - The list of NFT offers. + + +### xrplAccount.getNftByUri(uri, [isHexUri]) ⇒ Promise.<(Object\|null)> +Retrieves a specific NFT by its URI. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<(Object\|null)> - The NFT object or null if not found. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uri | string | | The URI of the NFT to retrieve. | +| [isHexUri] | boolean | false | Whether the URI is in hexadecimal format. | + + + +### xrplAccount.getAccountObjects(options) ⇒ Promise.<Array.<Object>> +Retrieves account objects for the account with the specified options. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array.<Object>> - The list of account objects. + +| Param | Type | Description | +| --- | --- | --- | +| options | Object | The options for retrieving account objects. | + + + +### xrplAccount.getNamespaceEntries(namespaceId, [options]) ⇒ Promise.<Array.<Object>> +Retrieves namespace entries for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array.<Object>> - The list of namespace entries. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| namespaceId | string | | The ID of the namespace to retrieve entries for. | +| [options] | Object | {} | The options for retrieving namespace entries. | + + + +### xrplAccount.getFlags() ⇒ Promise.<Object> +Retrieves the flags set on the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The account flags. + + +### xrplAccount.getAccountTrx([minLedgerIndex], [maxLedgerIndex], [isForward]) ⇒ Promise.<Array> +Retrieves account transactions within a specified ledger range. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array> - The list of transactions. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [minLedgerIndex] | number | -1 | The minimum ledger index to retrieve transactions from. | +| [maxLedgerIndex] | number | -1 | The maximum ledger index to retrieve transactions from. | +| [isForward] | boolean | true | Whether to retrieve transactions in forward order. | + + + +### xrplAccount.hasValidKeyPair() ⇒ Promise.<boolean> +Checks if the current wallet has a valid key pair for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<boolean> - True if the key pair is valid, otherwise false. + + +### xrplAccount.setAccountFields(fields, options) ⇒ Promise.<Object> +Sets account fields. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The transaction result. + +| Param | Type | Description | +| --- | --- | --- | +| fields | Object | The fields to set. | +| options | Object | Additional transaction options (optional). | + + + +### xrplAccount.prepareSetAccountFields(fields, [options]) ⇒ Promise.<Object> +Prepares an AccountSet transaction with the specified fields and options. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared AccountSet transaction. +**Throws**: + +- Will throw an error if no fields are provided and `allowEmptyAccountSet` is not true. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| fields | Object | | The fields to set for the account. Example: { Domain: "www.mydomain.com", Flags: { asfDefaultRipple: false, asfDisableMaster: true } } | +| [options] | Object | {} | Additional options for the transaction. Can include hook parameters. | + + + +### xrplAccount.setSignerList(signerList, [options]) ⇒ Promise.<Object> +Sets the signer list for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| signerList | Array | | The list of signers to set for the account. | +| [options] | Object | {} | Additional options for setting the signer list. | + + + +### xrplAccount.prepareSetSignerList(signerList, options) ⇒ Promise.<Object> +Set the signer list to the account. Setting signerQuorum = 0 in options, will remove the signerlist from the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Prepared transaction. + +| Param | Type | Description | +| --- | --- | --- | +| signerList | \* | (optional) An array of signers. Ex: [ {account:"ras24cvffvfbvfbbt5or4332", weight: 1}, {}, ...] | +| options | \* | Ex: {signerQuorum: 1, sequence: 6543233} | + + + +### xrplAccount.invoke(toAddr, [blobObj], [options]) ⇒ Promise.<Object> +Invokes a transaction to a specified address. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| toAddr | string | | The destination address. | +| [blobObj] | Object \| null | | Optional blob object with data and its format. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareInvoke(toAddr, [blobObj], [options]) ⇒ Promise.<Object> +Prepares an invoke transaction. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared invoke transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| toAddr | string | | The destination address. | +| [blobObj] | Object \| null | | Blob object containing data and whether it's in hex. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.makePayment(toAddr, amount, [currency], [issuer], [memos], [options]) ⇒ Promise.<Object> +Makes a payment to the specified address. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| toAddr | string | | The destination address. | +| amount | number \| string | | The amount to send. | +| [currency] | string \| null | null | Optional currency code. | +| [issuer] | string \| null | null | Optional issuer for non-XRP currencies. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareMakePayment(toAddr, amount, [currency], [issuer], [memos], [options]) ⇒ Promise.<Object> +Prepares a payment transaction. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared payment transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| toAddr | string | | The destination address. | +| amount | number \| string | | The amount to send. | +| [currency] | string \| null | null | Optional currency code. | +| [issuer] | string \| null | null | Optional issuer for non-XRP currencies. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.setTrustLine(currency, issuer, limit, [allowRippling], [memos], [options]) ⇒ Promise.<Object> +Sets a trust line with the specified parameters. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| currency | string | | The currency code for the trust line. | +| issuer | string | | The issuer of the currency. | +| limit | string | | The limit for the trust line. | +| [allowRippling] | boolean | false | Whether to allow rippling. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareSetTrustLine(currency, issuer, limit, [allowRippling], [memos], [options]) ⇒ Promise.<Object> +Prepares a trust line transaction. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared trust line transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| currency | string | | The currency code for the trust line. | +| issuer | string | | The issuer of the currency. | +| limit | string | | The limit for the trust line. | +| [allowRippling] | boolean | false | Whether to allow rippling. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.setRegularKey(regularKey, [memos], [options]) ⇒ Promise.<Object> +Sets the regular key for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| regularKey | string | | The regular key to set. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareSetRegularKey(regularKey, [memos], [options]) ⇒ Promise.<Object> +Prepares a transaction to set the regular key for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared regular key transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| regularKey | string | | The regular key to set. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareCashCheck(check, [options]) ⇒ Promise.<Object> +Cashes a check for the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| check | Object | | The check object with details. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.offerSell(sellAmount, sellCurrency, sellIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options]) ⇒ Promise.<Object> +Creates an offer to sell assets. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| sellAmount | number \| string | | The amount to sell. | +| sellCurrency | string | | The currency code of the asset to sell. | +| sellIssuer | string | | The issuer of the asset to sell. | +| forAmount | number \| string | | The amount to receive. | +| forCurrency | string | | The currency code of the asset to receive. | +| [forIssuer] | string \| null | null | The issuer of the asset to receive. | +| [expiration] | number | 4294967295 | The expiration time for the offer. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareOfferSell(sellAmount, sellCurrency, sellIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options]) ⇒ Promise.<Object> +Prepares a transaction to sell assets. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared offer sell transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| sellAmount | number \| string | | The amount to sell. | +| sellCurrency | string | | The currency code of the asset to sell. | +| sellIssuer | string | | The issuer of the asset to sell. | +| forAmount | number \| string | | The amount to receive. | +| forCurrency | string | | The currency code of the asset to receive. | +| [forIssuer] | string \| null | null | The issuer of the asset to receive. | +| [expiration] | number | 4294967295 | The expiration time for the offer. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.offerBuy(buyAmount, buyCurrency, buyIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options]) ⇒ Promise.<Object> +Creates an offer to buy assets. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| buyAmount | number \| string | | The amount to buy. | +| buyCurrency | string | | The currency code of the asset to buy. | +| buyIssuer | string | | The issuer of the asset to buy. | +| forAmount | number \| string | | The amount to give in exchange. | +| forCurrency | string | | The currency code of the asset to give in exchange. | +| [forIssuer] | string \| null | null | The issuer of the asset to give in exchange. | +| [expiration] | number | 4294967295 | The expiration time for the offer. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareOfferBuy(buyAmount, buyCurrency, buyIssuer, forAmount, forCurrency, [forIssuer], [expiration], [memos], [options]) ⇒ Promise.<Object> +Prepares an offer to buy assets. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared offer buy transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| buyAmount | number \| string | | The amount to buy. | +| buyCurrency | string | | The currency code of the asset to buy. | +| buyIssuer | string | | The issuer of the asset to buy. | +| forAmount | number \| string | | The amount to give in exchange. | +| forCurrency | string | | The currency code of the asset to give in exchange. | +| [forIssuer] | string \| null | null | The issuer of the asset to give in exchange. | +| [expiration] | number | 4294967295 | The expiration time for the offer. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.cancelOffer(offerSequence, [memos], [options]) ⇒ Promise.<Object> +Cancels an existing offer. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The result of the sign and submit operation. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| offerSequence | number | | The sequence number of the offer to cancel. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareCancelOffer(offerSequence, [memos], [options]) ⇒ Promise.<Object> +Prepares a transaction to cancel an offer. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared offer cancel transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| offerSequence | number | | The sequence number of the offer to cancel. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.subscribe() ⇒ Promise.<void> +Subscribes to the XRPL address stream for transaction updates. +Ensures only one subscription is active at a time. + +**Kind**: instance method of [XrplAccount](#XrplAccount) + + +### xrplAccount.unsubscribe() ⇒ Promise.<void> +Unsubscribes from the XRPL address stream. + +**Kind**: instance method of [XrplAccount](#XrplAccount) + + +### xrplAccount.submitTransactionBlob(txBlob) ⇒ Promise.<Object> +Submits a signed raw transaction. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Result of the transaction submission. + +| Param | Type | Description | +| --- | --- | --- | +| txBlob | string | Signed and encoded transaction as a hex string. | + + + +### xrplAccount.sign(tx, [isMultiSign]) ⇒ Object +Signs the given transaction and returns the signed blob and its hash. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Object - The signed transaction hash and blob. Format: {hash: string, tx_blob: string} + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| tx | Object | | Transaction object. | +| [isMultiSign] | boolean | false | Whether the transaction is for multisigning. | + + + +### xrplAccount.mintURIToken(uri, [digest], [flags], [options]) ⇒ Promise.<Object> +Mints a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Result of the mint transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uri | string | | The URI to mint as a token. | +| [digest] | string \| null | null | The optional digest for the token. | +| [flags] | Object | {} | Flags to control token properties (e.g., isBurnable). | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareMintURIToken(uri, [digest], [flags], [options]) ⇒ Promise.<Object> +Prepares the minting of a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared mint transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uri | string | | The URI to mint as a token. | +| [digest] | string \| null | null | The optional digest for the token. | +| [flags] | Object | {} | Flags to control token properties. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.burnURIToken(uriTokenID, [options]) ⇒ Promise.<Object> +Burns a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Result of the burn transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriTokenID | string | | The ID of the URI token to burn. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareBurnURIToken(uriTokenID, [options]) ⇒ Promise.<Object> +Prepares the burning of a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared burn transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriTokenID | string | | The ID of the URI token to burn. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.sellURIToken(uriTokenID, amount, currency, [issuer], [toAddr], [memos], [options]) ⇒ Promise.<Object> +Creates a sell offer for a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Result of the sell transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriTokenID | string | | The ID of the URI token to sell. | +| amount | string \| number | | The amount to sell the token for. | +| currency | string | | The currency code for the sale. | +| [issuer] | string \| null | null | The issuer of the currency. | +| [toAddr] | string \| null | null | The address of the buyer. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareSellURIToken(uriTokenID, amount, currency, [issuer], [toAddr], [memos], [options]) ⇒ Promise.<Object> +Prepares a sell offer for a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared sell offer transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriTokenID | string | | The ID of the URI token to sell. | +| amount | string \| number | | The amount to sell the token for. | +| currency | string | | The currency code for the sale. | +| [issuer] | string \| null | null | The issuer of the currency. | +| [toAddr] | string \| null | null | The address of the buyer. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.buyURIToken(uriToken, [memos], [options]) ⇒ Promise.<Object> +Buys a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Result of the buy transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriToken | Object | | The URI token object to buy. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareBuyURIToken(uriToken, [memos], [options]) ⇒ Promise.<Object> +Prepares a buy offer for a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared buy offer transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriToken | Object | | The URI token object to buy. | +| [memos] | Array \| null | | Optional memos to attach to the transaction. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.clearURITokenOffer(uriTokenID, [options]) ⇒ Promise.<Object> +Clears a sell offer for a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Result of the clear offer transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriTokenID | string | | The ID of the URI token offer to clear. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.prepareClearURITokenOffer(uriTokenID, [options]) ⇒ Promise.<Object> +Prepares the clearing of a sell offer for a URI token. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The prepared clear offer transaction. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uriTokenID | string | | The ID of the URI token offer to clear. | +| [options] | Object | {} | Additional options for the transaction. | + + + +### xrplAccount.getURITokens(options) ⇒ Promise.<Array> +Retrieves all URI tokens associated with the account. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Array> - List of URI tokens. + +| Param | Type | Description | +| --- | --- | --- | +| options | Object | Additional options for the retrieval. | + + + +### xrplAccount.getURITokenByUri(uri, [isHexUri]) ⇒ Promise.<Object> +Retrieves a URI token by its URI. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - The URI token object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uri | string | | The URI of the token to retrieve. | +| [isHexUri] | boolean | false | Whether the URI is in hex format. | + + + +### xrplAccount.generateIssuedURITokenId(uri, [isHexUri]) ⇒ string +Generates the issued URI token ID from a given URI. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: string - The generated URI token ID. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| uri | string | | The URI to generate the token ID from. | +| [isHexUri] | boolean | false | Whether the URI is in hex format. | + + + +### xrplAccount.signAndSubmit(preparedTransaction, submissionRef) ⇒ Promise.<Object> +Sign and submit prepared transaction. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - result of the submitted transaction. + +| Param | Type | Description | +| --- | --- | --- | +| preparedTransaction | object | Prepared transaction. | +| submissionRef | object | [Optional] Reference object to take submission references. | + + + +### xrplAccount.submitMultisigned(tx) ⇒ Promise.<Object> +Submit a multi-singed transaction. + +**Kind**: instance method of [XrplAccount](#XrplAccount) +**Returns**: Promise.<Object> - Result of the transaction. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | Signed transaction. | + + + +## XrplApi +Class representing an XRPL API client. + +**Kind**: global class + +* [XrplApi](#XrplApi) + * [new XrplApi(rippledServer, [options])](#new_XrplApi_new) + * [.on(event, handler)](#XrplApi+on) + * [.once(event, handler)](#XrplApi+once) + * [.off(event, [handler])](#XrplApi+off) + * [.connect()](#XrplApi+connect) ⇒ Promise.<void> + * [.disconnect()](#XrplApi+disconnect) ⇒ Promise.<void> + * [.isValidKeyForAddress(publicKey, address)](#XrplApi+isValidKeyForAddress) ⇒ Promise.<boolean> + * [.isAccountExists(address)](#XrplApi+isAccountExists) ⇒ Promise.<boolean> + * [.getServerState([ledgerIdx])](#XrplApi+getServerState) ⇒ Promise.<string> + * [.getAccountInfo(address)](#XrplApi+getAccountInfo) ⇒ Promise.<Object> + * [.getServerDefinition()](#XrplApi+getServerDefinition) ⇒ Promise.<Object> + * [.getServerInfo()](#XrplApi+getServerInfo) ⇒ Promise.<Object> + * [.getAccountObjects(address, [options])](#XrplApi+getAccountObjects) ⇒ Promise.<Array.<Object>> + * [.getNamespaceEntries(address, namespaceId, [options])](#XrplApi+getNamespaceEntries) ⇒ Promise.<Array.<Object>> + * [.getNftOffers(address, [options])](#XrplApi+getNftOffers) ⇒ Promise.<Array.<Object>> + * [.getTrustlines(address, [options])](#XrplApi+getTrustlines) ⇒ Promise.<Array.<Object>> + * [.getAccountTrx(address, [options])](#XrplApi+getAccountTrx) ⇒ Promise.<Array.<Object>> + * [.getNfts(address, [options])](#XrplApi+getNfts) ⇒ Promise.<Array.<Object>> + * [.getOffers(address, [options])](#XrplApi+getOffers) ⇒ Promise.<Array.<Object>> + * [.getSellOffers(nfTokenId, [options])](#XrplApi+getSellOffers) ⇒ Promise.<Array.<Object>> + * [.getBuyOffers(nfTokenId, [options])](#XrplApi+getBuyOffers) ⇒ Promise.<Array.<Object>> + * [.getLedgerEntry(index, [options])](#XrplApi+getLedgerEntry) ⇒ Promise.<(Object\|null)> + * [.getURITokenByIndex(index)](#XrplApi+getURITokenByIndex) ⇒ Promise.<(Object\|null)> + * [.getTxnInfo(txnHash, options)](#XrplApi+getTxnInfo) ⇒ Promise.<Object> + * [.subscribeToAddress(address, handler)](#XrplApi+subscribeToAddress) ⇒ Promise.<void> + * [.unsubscribeFromAddress(address, handler)](#XrplApi+unsubscribeFromAddress) ⇒ Promise.<void> + * [.getTransactionFee(txBlob)](#XrplApi+getTransactionFee) ⇒ Promise.<number> + * [.getTransactionValidatedResults(txHash)](#XrplApi+getTransactionValidatedResults) ⇒ + * [.submitMultisignedAndWait(tx, submissionRef)](#XrplApi+submitMultisignedAndWait) ⇒ + * [.submitMultisigned(tx)](#XrplApi+submitMultisigned) ⇒ + * [.submitAndWait(tx_blob, submissionRef)](#XrplApi+submitAndWait) ⇒ + * [.submit(tx_blob)](#XrplApi+submit) ⇒ + * [.multiSign(transactions)](#XrplApi+multiSign) ⇒ string + + + +### new XrplApi(rippledServer, [options]) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| rippledServer | string \| null | null | The URL of the primary rippled server or null if not used. | +| [options] | Object | {} | Optional configuration options. | +| [options.fallbackRippledServers] | Array.<string> | [] | List of fallback server URLs. | +| [options.xrplClientOptions] | Object | {} | Options for the xrpl client. | +| [options.autoReconnect] | boolean | true | Whether to automatically reconnect. | + + + +### xrplApi.on(event, handler) +Adds an event listener for a specified event. + +**Kind**: instance method of [XrplApi](#XrplApi) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The event to listen for. | +| handler | function | The function to call when the event occurs. | + + + +### xrplApi.once(event, handler) +Adds a one-time event listener for a specified event. + +**Kind**: instance method of [XrplApi](#XrplApi) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The event to listen for. | +| handler | function | The function to call when the event occurs. | + + + +### xrplApi.off(event, [handler]) +Removes an event listener for a specified event. + +**Kind**: instance method of [XrplApi](#XrplApi) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | The event to stop listening for. | +| [handler] | function | | The function to remove or null to remove all handlers. | + + + +### xrplApi.connect() ⇒ Promise.<void> +Connects to the XRPL API. + +**Kind**: instance method of [XrplApi](#XrplApi) + + +### xrplApi.disconnect() ⇒ Promise.<void> +Disconnects from the XRPL API. + +**Kind**: instance method of [XrplApi](#XrplApi) + + +### xrplApi.isValidKeyForAddress(publicKey, address) ⇒ Promise.<boolean> +Checks if the given public key is valid for the specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<boolean> - Returns true if the public key is valid for the address. + +| Param | Type | Description | +| --- | --- | --- | +| publicKey | string | The public key to check. | +| address | string | The address to check against. | + + + +### xrplApi.isAccountExists(address) ⇒ Promise.<boolean> +Checks if an account exists at the specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<boolean> - Returns true if the account exists. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The account address. | + + + +### xrplApi.getServerState([ledgerIdx]) ⇒ Promise.<string> +Gets the server state at the specified ledger index. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<string> - The server state. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [ledgerIdx] | string | "\"current\"" | The ledger index to get the state for. | + + + +### xrplApi.getAccountInfo(address) ⇒ Promise.<Object> +Gets account information for a specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Object> - The account information. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The account address. | + + + +### xrplApi.getServerDefinition() ⇒ Promise.<Object> +Gets the server definitions. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Object> - The server definitions. + + +### xrplApi.getServerInfo() ⇒ Promise.<Object> +Gets information about the server. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Object> - The server information. + + +### xrplApi.getAccountObjects(address, [options]) ⇒ Promise.<Array.<Object>> +Gets account objects for a specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The account objects. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string | | The account address. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getNamespaceEntries(address, namespaceId, [options]) ⇒ Promise.<Array.<Object>> +Gets namespace entries for a specified address and namespace ID. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The namespace entries. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string | | The account address. | +| namespaceId | string | | The namespace ID. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getNftOffers(address, [options]) ⇒ Promise.<Array.<Object>> +Gets NFT offers for a specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The NFT offers. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string | | The account address. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getTrustlines(address, [options]) ⇒ Promise.<Array.<Object>> +Gets trustlines for a specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The trustlines. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string | | The account address. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getAccountTrx(address, [options]) ⇒ Promise.<Array.<Object>> +Gets account transactions for a specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The account transactions. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string | | The account address. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getNfts(address, [options]) ⇒ Promise.<Array.<Object>> +Gets NFTs for a specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The NFTs. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string | | The account address. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getOffers(address, [options]) ⇒ Promise.<Array.<Object>> +Gets offers for a specified address. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The offers. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| address | string | | The account address. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getSellOffers(nfTokenId, [options]) ⇒ Promise.<Array.<Object>> +Gets sell offers for a specified NFT token ID. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The sell offers. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| nfTokenId | string | | The NFT token ID. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getBuyOffers(nfTokenId, [options]) ⇒ Promise.<Array.<Object>> +Gets buy offers for a specified NFT token ID. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Array.<Object>> - The buy offers. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| nfTokenId | string | | The NFT token ID. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getLedgerEntry(index, [options]) ⇒ Promise.<(Object\|null)> +Gets ledger entry by index. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<(Object\|null)> - The ledger entry or null if not found. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | string | | The ledger index. | +| [options] | Object | {} | Optional parameters for the request. | + + + +### xrplApi.getURITokenByIndex(index) ⇒ Promise.<(Object\|null)> +Gets the URI token by index. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<(Object\|null)> - The URI token entry or null if not found. + +| Param | Type | Description | +| --- | --- | --- | +| index | string | The index of the URI token. | + + + +### xrplApi.getTxnInfo(txnHash, options) ⇒ Promise.<Object> +Gets transaction information. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<Object> - The transaction information. + +| Param | Type | Description | +| --- | --- | --- | +| txnHash | string | The hash of the transaction. | +| options | Object | Optional parameters for the request. | + + + +### xrplApi.subscribeToAddress(address, handler) ⇒ Promise.<void> +Subscribes to address updates. + +**Kind**: instance method of [XrplApi](#XrplApi) + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The address to subscribe to. | +| handler | function | The handler function for address updates. | + + + +### xrplApi.unsubscribeFromAddress(address, handler) ⇒ Promise.<void> +Unsubscribes from address updates. + +**Kind**: instance method of [XrplApi](#XrplApi) + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The address to unsubscribe from. | +| handler | function | The handler function to remove. | + + + +### xrplApi.getTransactionFee(txBlob) ⇒ Promise.<number> +Gets the transaction fee. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Promise.<number> - The transaction fee. + +| Param | Type | Description | +| --- | --- | --- | +| txBlob | string | The transaction blob. | + + + +### xrplApi.getTransactionValidatedResults(txHash) ⇒ +Get the transaction results if validated. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: Validated results of the transaction. + +| Param | Type | Description | +| --- | --- | --- | +| txHash | string | Hash of the transaction to check. | + + + +### xrplApi.submitMultisignedAndWait(tx, submissionRef) ⇒ +Submit a multi-signature transaction and wait for validation. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: response object of the validated transaction. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | Multi-signed transaction object. | +| submissionRef | object | [Optional] Reference object to take submission references. | + + + +### xrplApi.submitMultisigned(tx) ⇒ +Only submit a multi-signature transaction. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: response object of the submitted transaction. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | Multi-signed transaction object. | + + + +### xrplApi.submitAndWait(tx_blob, submissionRef) ⇒ +Submit a single-signature transaction. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: response object of the validated transaction. + +| Param | Type | Description | +| --- | --- | --- | +| tx_blob | string | Signed transaction object. | +| submissionRef | object | [Optional] Reference object to take submission references. | + + + +### xrplApi.submit(tx_blob) ⇒ +Only submit a single-signature transaction. + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: response object of the submitted transaction. + +| Param | Type | Description | +| --- | --- | --- | +| tx_blob | string | Signed transaction object. | + + + +### xrplApi.multiSign(transactions) ⇒ string +Joins the given array of signed transactions into one multi-signed transaction. +For more details: https://js.xrpl.org/functions/multisign.html + +**Kind**: instance method of [XrplApi](#XrplApi) +**Returns**: string - A single multi-signed transaction in string format that contains all signers from the input transactions. +**Throws**: + +- Error If the transactions array is empty. + + +| Param | Type | Description | +| --- | --- | --- | +| transactions | Array.<(string\|object)> | An array of signed transactions, either as serialized strings or transaction objects, to combine into a single multi-signed transaction. | + diff --git a/docs/filelist b/docs/filelist new file mode 100644 index 0000000..971cde5 --- /dev/null +++ b/docs/filelist @@ -0,0 +1,19 @@ +src/defaults.js +src/clients/hook-clients/registry-client.js +rc/clients/hook-clients/governor-client.js +src/clients/hook-clients/heartbeat-client.js +src/clients/hook-clients/hook-client-factory.js +src/clients/base-evernode-client.js +src/clients/tenant-client.js +src/clients/host-client.js +src/clients/foundation-client.js +src/xrpl-api.js +src/xrpl-common.js +src/xrpl-account.js +src/evernode-common.js +src/state-helpers.js +src/util-helpers.js +src/transaction-helper.js +src/encryption-helper.js +src/evernode-helpers.js +src/xfl-helpers.js \ No newline at end of file diff --git a/docs/init-docs.js b/docs/init-docs.js new file mode 100644 index 0000000..7bc4516 --- /dev/null +++ b/docs/init-docs.js @@ -0,0 +1,44 @@ +const fs = require('fs'); +const path = require('path'); + +const updateJSDocUtil = () => { + const jsdocUtilDumperPath = path.join(__dirname, '../node_modules/jsdoc/lib/jsdoc/util/dumper.js'); + + let utilFileContent = fs.readFileSync(jsdocUtilDumperPath, 'utf8'); + + const oldUtilFunction = `exports.dump = function(...args) { + const result = []; + let walker; + + for (let arg of args) { + walker = new ObjectWalker(); + result.push( JSON.stringify(walker.walk(arg), null, 4) ); + } + + return result.join('\\n'); +};`; + + const newUtilFunction = `exports.dump = function(...args) { + const result = []; + let walker; + + for (let arg of args) { + walker = new ObjectWalker(); + result.push( JSON.stringify(walker.walk(arg), (key, value) => typeof value == 'bigint' ? value.toString() : value, 4) ); + } + + return result.join('\\n'); +};`; + + if (utilFileContent.includes(oldUtilFunction)) { + utilFileContent = utilFileContent.replace(oldUtilFunction, newUtilFunction); + fs.writeFileSync(jsdocUtilDumperPath, utilFileContent, 'utf8'); + console.log('JSDoc utility function modified successful!'); + } else { + console.log('JSDoc obsolete utility function is not found.'); + } +}; + + + +updateJSDocUtil(); diff --git a/package.json b/package.json index 2c7c728..d466117 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "lint": "./node_modules/.bin/eslint src/**/*.js", "build": "npm run lint && ncc build src/index.js -e elliptic -e xrpl -e ripple-address-codec -e ripple-binary-codec -e ripple-keypairs -o dist/ && cp evernode-license.pdf dist/", "bundle": "npm run build && ./clean-pkg.sh", - "publish": "npm run bundle && cp npm-readme.md dist/README.md && npm publish ./dist" + "publish": "npm run bundle && cp npm-readme.md dist/README.md && npm publish ./dist", + "docs": "echo '# Evernode JS API Documentation' > docs/evernode-js-api.md && xargs jsdoc2md < docs/filelist >> docs/evernode-js-api.md" }, "dependencies": { "elliptic": "6.5.4", @@ -23,6 +24,7 @@ "xrpl-accountlib": "3.2.9" }, "devDependencies": { - "eslint": "8.3.0" + "eslint": "8.3.0", + "jsdoc-to-markdown": "^9.0.1" } } \ No newline at end of file diff --git a/src/clients/base-evernode-client.js b/src/clients/base-evernode-client.js index 6591890..0963641 100644 --- a/src/clients/base-evernode-client.js +++ b/src/clients/base-evernode-client.js @@ -30,6 +30,20 @@ const REPUTATION_VALUE_PARAM_OFFSET = 20; // By reputation address const HOST_DEREG_FROM_REP_PARAM_SIZE = 53; +/** + * Creates an instance of BaseEvernodeClient. + * + * @param {string} xrpAddress - The XRP address associated with the client. + * @param {string} xrpSecret - The XRP secret associated with the client. + * @param {Array} watchEvents - An array of event names to watch. + * @param {boolean} [autoSubscribe=false] - Whether to automatically subscribe to events. + * @param {Object} [options={}] - Optional configuration options. + * @param {string} [options.governorAddress] - The governor address. Defaults to a predefined value if not provided. + * @param {XrplApi} [options.xrplApi] - An instance of XrplApi. If not provided, a new instance will be created. + * @param {string} [options.rippledServer] - The URL of the rippled server to use if a new XrplApi instance is created. + * @param {Object} [options.config] - Optional configuration settings. + * @param {string} [options.messagePrivateKey] - The private key for message encryption, if required. + */ class BaseEvernodeClient { #watchEvents; @@ -64,8 +78,8 @@ 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. + * @param {string} event - The name of the event to listen for. + * @param {function} handler - The callback function to handle the event. The function takes the event object as a parameter. */ on(event, handler) { this.events.on(event, handler); @@ -91,7 +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 success. + * @returns Returns `true` if the connection is successful. */ async connect(options = {}) { if (this.connected) @@ -140,7 +154,7 @@ class BaseEvernodeClient { /** * Get the EVR balance in the account. - * @returns The available EVR amount as a 'string'. + * @returns The available EVR amount as a string. */ async getEVRBalance() { const lines = await this.xrplAcc.getTrustLines(EvernodeConstants.EVR, this.config.evrIssuerAddress); @@ -152,7 +166,7 @@ class BaseEvernodeClient { /** * Get all XRPL hook states in the registry account. - * @returns The list of hook states including Evernode configuration and hosts. + * @returns The list of hook states, including Evernode configuration and hosts. */ async getHookStates() { const regAcc = new XrplAccount(this.governorAddress, null, { xrplApi: this.xrplApi }); @@ -166,7 +180,7 @@ class BaseEvernodeClient { /** * Get the moment from the given index (timestamp). * @param {number} index [Optional] Index (timestamp) to get the moment value. - * @returns The moment of the given index (timestamp) as 'number'. Returns current moment if index (timestamp) is not given. + * @returns The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. */ async getMoment(index = null) { const i = index || UtilHelpers.getCurrentUnixTime(); @@ -191,7 +205,7 @@ class BaseEvernodeClient { /** * Get Evernode configuration - * @returns An object with all the configuration and their values. + * @returns An object containing all the configuration keys and their corresponding values. */ async #getEvernodeConfig() { const configStateKeys = { @@ -257,9 +271,10 @@ 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 HookParameters before passing the transaction to this function. + * Extracts the transaction info from a given transaction. + * Note: You need to deserialize HookParameters before passing the transaction to this function. + * @param {object} tx - The transaction object to be deserialized and extracted. + * @returns {} The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. */ async extractEvernodeEvent(tx) { let eventType; @@ -1072,6 +1087,7 @@ class BaseEvernodeClient { * @param {string} shortName Short name for the proposal candidate. * @param {*} options [Optional] transaction options. * @returns Proposed candidate id. + * @ignore */ async _propose(hashes, shortName, options = {}) { const hashesBuf = Buffer.from(hashes, 'hex'); @@ -1122,6 +1138,7 @@ class BaseEvernodeClient { * @param {string} candidateId Id of the candidate in hex format. * @param {*} options [Optional] transaction options. * @returns Transaction result. + * @ignore */ async _withdraw(candidateId, options = {}) { const candidateIdBuf = Buffer.from(candidateId, 'hex'); @@ -1144,6 +1161,7 @@ class BaseEvernodeClient { * @param {string} hostAddress Address of the dud host. * @param {*} options [Optional] transaction options. * @returns Transaction result. + * @ignore */ async _reportDudHost(hostAddress, options = {}) { const candidateId = StateHelpers.getDudHostCandidateId(hostAddress); diff --git a/src/clients/foundation-client.js b/src/clients/foundation-client.js index 19a9f6a..b0ec00d 100644 --- a/src/clients/foundation-client.js +++ b/src/clients/foundation-client.js @@ -15,8 +15,21 @@ const REPUTATION_PARAM_SIZE = 21; const FoundationEvents = {} +/** + * FoundationClient class to manage and interact with foundation operations. + * It extends the BaseEvernodeClient. + * + * @extends BaseEvernodeClient + */ class FoundationClient extends BaseEvernodeClient { + /** + * Creates an instance of FoundationClient. + * + * @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 FoundationClient. + */ constructor(xrpAddress, xrpSecret, options = {}) { super(xrpAddress, xrpSecret, Object.values(FoundationEvents), false, options); } diff --git a/src/clients/hook-clients/governor-client.js b/src/clients/hook-clients/governor-client.js index 3aaf07f..aa402f8 100644 --- a/src/clients/hook-clients/governor-client.js +++ b/src/clients/hook-clients/governor-client.js @@ -16,6 +16,12 @@ const GovernorEvents = { LinkedDudHostCandidateRemoved: EvernodeEvents.LinkedDudHostCandidateRemoved } +/** + * 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 { constructor(options = {}) { super((options.governorAddress || Defaults.values.governorAddress), null, Object.values(GovernorEvents), false, options); diff --git a/src/clients/hook-clients/heartbeat-client.js b/src/clients/hook-clients/heartbeat-client.js index d90d288..5a7551f 100644 --- a/src/clients/hook-clients/heartbeat-client.js +++ b/src/clients/hook-clients/heartbeat-client.js @@ -6,6 +6,12 @@ const HeartbeatEvents = { FoundationVoted: EvernodeEvents.FoundationVoted } +/** + * 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 { constructor(options = {}) { super(options.heartbeatAddress, null, Object.values(HeartbeatEvents), false, options); diff --git a/src/clients/hook-clients/hook-client-factory.js b/src/clients/hook-clients/hook-client-factory.js index 42074be..4f718fb 100644 --- a/src/clients/hook-clients/hook-client-factory.js +++ b/src/clients/hook-clients/hook-client-factory.js @@ -4,11 +4,17 @@ const { GovernorClient } = require("./governor-client"); const { HeartbeatClient } = require("./heartbeat-client"); const { ReputationClient } = require("./reputation-client"); +/** + * A factory class for creating different types of hook clients based on the provided hook type. + * @class + */ class HookClientFactory { /** * Creates a hook client from given type. - * @param {string} hookType Type of the Required Hook. (Supported Hook types 'GOVERNOR', 'REGISTRY' and 'HEARTBEAT') - * @returns Instance of requested HookClient 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} - 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. */ static async create(hookType, options = {}) { let governorClient; diff --git a/src/clients/hook-clients/registry-client.js b/src/clients/hook-clients/registry-client.js index 22171b4..f539951 100644 --- a/src/clients/hook-clients/registry-client.js +++ b/src/clients/hook-clients/registry-client.js @@ -11,6 +11,12 @@ const RegistryEvents = { HostReputationUpdated: EvernodeEvents.HostReputationUpdated } +/** + * 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 { constructor(options = {}) { @@ -18,8 +24,8 @@ class RegistryClient extends BaseEvernodeClient { } /** - * Gets all the active hosts registered in ledger. - * @returns The list of active hosts. + * Retrieves all active hosts registered in the ledger. + * @returns {Promise} - A promise that resolves to an array of active hosts. */ async getActiveHostsFromLedger() { const hosts = await this.getAllHostsFromLedger(); diff --git a/src/clients/hook-clients/reputation-client.js b/src/clients/hook-clients/reputation-client.js index 64db00e..8cb3057 100644 --- a/src/clients/hook-clients/reputation-client.js +++ b/src/clients/hook-clients/reputation-client.js @@ -3,6 +3,12 @@ const { BaseEvernodeClient } = require("../base-evernode-client"); 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 { constructor(options = {}) { diff --git a/src/clients/host-client.js b/src/clients/host-client.js index d9eb728..e2a7553 100644 --- a/src/clients/host-client.js +++ b/src/clients/host-client.js @@ -64,8 +64,21 @@ const IPV6_FAMILY = 6; const MAX_HOST_LEDGER_OFFSET = 30; const TX_RETRY_INTERVAL = 10000; +/** + * HostClient class to manage host operations. + * It extends the BaseEvernodeClient. + * + * @extends BaseEvernodeClient + */ 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. + */ constructor(xrpAddress, xrpSecret, options = {}) { super(xrpAddress, xrpSecret, Object.values(HostEvents), true, options); } diff --git a/src/clients/tenant-client.js b/src/clients/tenant-client.js index 914f709..aac15f5 100644 --- a/src/clients/tenant-client.js +++ b/src/clients/tenant-client.js @@ -17,12 +17,29 @@ const TenantEvents = { ExtendError: EvernodeEvents.ExtendError, } +/** + * TenantClient class to manage tenant operations. + * It extends the BaseEvernodeClient. + * + * @extends BaseEvernodeClient + */ 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. + */ constructor(xrpAddress, xrpSecret, options = {}) { super(xrpAddress, xrpSecret, Object.values(TenantEvents), false, options); } + /** + * Prepare the tenant account with account fields and trust lines. + * @param {Object} [options={}] - Optional configuration for the account setup. + */ async prepareAccount(options = {}) { try { if (!await this.xrplAcc.getMessageKey()) @@ -33,6 +50,13 @@ class TenantClient extends BaseEvernodeClient { } } + /** + * Retrieves and validates a lease host based on the given host address. + * + * @param {string} hostAddress - The XRP Ledger address of the host. + * @returns {Promise} - Returns the host object if valid and active. + * @throws Will throw an error if the host is invalid, inactive, or not registered. + */ async getLeaseHost(hostAddress) { const host = new XrplAccount(hostAddress, null, { xrplApi: this.xrplApi }); // Find an owned URI token with matching Evernode host NFT prefix. diff --git a/src/defaults.js b/src/defaults.js index 85705e3..8ddfd2d 100644 --- a/src/defaults.js +++ b/src/defaults.js @@ -31,6 +31,9 @@ const getDefinitions = async () => { }); } +/** + * Defaults class is responsible for retrieving and overriding the default Evernode network configurations. + */ class Defaults { /** * Load defaults from the public definitions json. diff --git a/src/encryption-helper.js b/src/encryption-helper.js index eaa297f..4956a0e 100644 --- a/src/encryption-helper.js +++ b/src/encryption-helper.js @@ -56,6 +56,9 @@ class secp256k1 { } } +/** + * EncryptionHelper class is responsible for encrypt and decrypt functions for messages. + */ class EncryptionHelper { static contentFormat = 'base64'; static keyFormat = 'hex'; @@ -74,6 +77,14 @@ class EncryptionHelper { return format === this.secp256k1KeyType ? secp256k1 : ed25519; } + /** + * Encrypts a message using the given public key. + * + * @param {string} publicKey - The public key to use for encryption. + * @param {Object} message - The message object to be encrypted. + * @param {Object} [options={}] - Optional encryption parameters. + * @returns {Promise} A promise that resolves to the encrypted message in base64 format, or null if encryption fails. + */ static async encrypt(publicKey, message, options = {}) { const publicKeyBuf = Buffer.from(publicKey, this.keyFormat); const messageBuf = Buffer.from(JSON.stringify(message)); @@ -82,6 +93,13 @@ class EncryptionHelper { return result ? result.toString(this.contentFormat) : null; } + /** + * Decrypts an encrypted message using the given private key. + * + * @param {string} privateKey - The private key to use for decryption. + * @param {string} encrypted - The encrypted message string. + * @returns {Promise} A promise that resolves to the decrypted message as an object, or null if decryption fails. + */ static async decrypt(privateKey, encrypted) { const privateKeyBuf = Buffer.from(privateKey, this.keyFormat); const encryptedBuf = Buffer.from(encrypted, this.contentFormat); diff --git a/src/evernode-helpers.js b/src/evernode-helpers.js index 479a97d..fa7b5b8 100644 --- a/src/evernode-helpers.js +++ b/src/evernode-helpers.js @@ -1,14 +1,31 @@ const { EvernodeConstants, URITokenTypes } = require('./evernode-common'); const { TransactionHelper } = require('./transaction-helper'); +const { XrplApi } = require('./xrpl-api'); const NFT_PAGE_LEDGER_ENTRY_TYPE_HEX = '0050'; +/** + * Provides various utility functions for working with leases, tokens, and ledger entries within the Xahau ecosystem. + */ class EvernodeHelpers { + /** + * Retrieves URI tokens that are valid leases for the specified XRPL account. + * + * @param {Object} xrplAcc - The XRPL account object. + * @returns {Promise>} A promise that resolves to an array of URI tokens that are valid leases. + */ static async getLeases(xrplAcc) { const hostUriOffers = (await xrplAcc.getURITokens()).filter(uriToken => uriToken.Issuer == xrplAcc.address && this.isValidURI(uriToken.URI, EvernodeConstants.LEASE_TOKEN_PREFIX_HEX) && uriToken.Flags == 1); return hostUriOffers; } + /** + * Retrieves a lease by its index from the XRPL ledger. + * + * @param {XrplApi} xrplApi - The XRPL API object. + * @param {string} index - The ledger entry index. + * @returns {Promise} A promise that resolves to the lease entry or null if not found or invalid. + */ static async getLeaseByIndex(xrplApi, index) { const entry = await xrplApi.getLedgerEntry(index); if (!entry || entry.LedgerEntryType !== 'URIToken' || !(this.isValidURI(entry.URI, EvernodeConstants.LEASE_TOKEN_PREFIX_HEX) && entry.Flags == 1)) @@ -16,16 +33,37 @@ class EvernodeHelpers { return entry; } + /** + * Retrieves all leases that have offers (i.e., an associated amount) for the specified XRPL account. + * + * @param {Object} xrplAcc - The XRPL account object. + * @returns {Promise>} A promise that resolves to an array of URI tokens with offers. + */ static async getLeaseOffers(xrplAcc) { const hostUriOffers = (await this.getLeases(xrplAcc)).filter(uriToken => uriToken.Amount); return hostUriOffers; } + /** + * Retrieves leases that do not have offers (i.e., no amount associated) for the specified XRPL account. + * + * @param {Object} xrplAcc - The XRPL account object. + * @returns {Promise>} A promise that resolves to an array of unoffered URI tokens. + */ static async getUnofferedLeases(xrplAcc) { const hostUriTokens = (await this.getLeases(xrplAcc)).filter(uriToken => !uriToken.Amount); return hostUriTokens } + /** + * Finds the NFT page and location of a specific NFToken in the XRPL ledger. + * + * @param {string} nfTokenId - The ID of the NFToken. + * @param {Object} xrplAcc - The XRPL account object. + * @param {Object} xrplApi - The XRPL API object. + * @param {boolean} [buffer=true] - Whether to return the result as a buffer. + * @returns {Promise} A promise that resolves to either a buffer with the NFT page and location or an object with page and location details. + */ static async getNFTPageAndLocation(nfTokenId, xrplAcc, xrplApi, buffer = true) { const nftPageApprxKeylet = xrplAcc.generateKeylet('nftPage', { nfTokenId: nfTokenId }); @@ -56,11 +94,26 @@ class EvernodeHelpers { return nftPageInfo; } + /** + * Calculates the reward quota for a specific epoch. + * + * @param {number} epoch - The epoch number. + * @param {number} firstEpochRewardQuota - The reward quota for the first epoch. + * @returns {number} The calculated reward quota for the specified epoch. + */ static getEpochRewardQuota(epoch, firstEpochRewardQuota) { const div = (epoch > 1) ? Math.pow(2, epoch - 1) : 1; return firstEpochRewardQuota / div; } + /** + * Checks if a given URI is valid based on a pattern and token category. + * + * @param {string} uri - The URI to validate. + * @param {string} pattern - The pattern to match the URI against. + * @param {string} [tokenCategory=URITokenTypes.LEASE_URI_TOKEN] - The token category (default is a lease URI token). + * @returns {boolean} Returns true if the URI is valid, false otherwise. + */ static isValidURI(uri, pattern, tokenCategory = URITokenTypes.LEASE_URI_TOKEN) { if (tokenCategory === URITokenTypes.LEASE_URI_TOKEN) { uri = TransactionHelper.hexToASCII(uri); diff --git a/src/state-helpers.js b/src/state-helpers.js index 71bb549..3da783c 100644 --- a/src/state-helpers.js +++ b/src/state-helpers.js @@ -145,6 +145,9 @@ const HOST_EMAIL_ADDRESS_LEN = 40; const STATE_KEY_SIZE = 32; const ACCOUNT_ID_SIZE = 20; +/** + * Provides various utility functions for working with States. + */ class StateHelpers { static StateTypes = { TOKEN_ID: 'tokenId', @@ -160,6 +163,12 @@ class StateHelpers { SEC: "SEC" } + /** + * Retrieves the state data for a specific key from an array of states. + * @param {Array} states - Array of state objects. + * @param {string} key - Key for the state data. + * @returns {Object|null} The state data or null if not found. + */ static getStateData(states, key) { const state = states.find(s => key === s.key); if (!state) @@ -168,6 +177,12 @@ class StateHelpers { return state.data; } + /** + * Decodes reputation host address state from buffers. + * @param {Buffer} stateKeyBuf - Buffer containing the state key. + * @param {Buffer} stateDataBuf - Buffer containing the state data. + * @returns {Object} Decoded state data including host address and reputation metrics. + */ static decodeReputationHostAddressState(stateKeyBuf, stateDataBuf) { const keyOffset = STATE_KEY_SIZE - ACCOUNT_ID_SIZE; const data = { @@ -183,6 +198,12 @@ class StateHelpers { return data; } + /** + * Decodes reputation host order address state from buffers. + * @param {Buffer} stateKeyBuf - Buffer containing the state key. + * @param {Buffer} stateDataBuf - Buffer containing the state data. + * @returns {Object} Decoded state data including moment and ordered ID. + */ static decodeReputationHostOrderAddressState(stateKeyBuf, stateDataBuf) { const keyOffset = STATE_KEY_SIZE - ACCOUNT_ID_SIZE - 8; const data = { @@ -193,6 +214,12 @@ class StateHelpers { return data; } + /** + * Decodes reputation host ordered ID state from buffers. + * @param {Buffer} stateKeyBuf - Buffer containing the state key. + * @param {Buffer} stateDataBuf - Buffer containing the state data. + * @returns {Object} Decoded state data including moment and ordered ID. + */ static decodeReputationHostOrderedIdState(stateKeyBuf, stateDataBuf) { const keyOffset = STATE_KEY_SIZE - 16; const data = { @@ -203,6 +230,12 @@ class StateHelpers { return data; } + /** + * Decodes reputation host count state from buffers. + * @param {Buffer} stateKeyBuf - Buffer containing the state key. + * @param {Buffer} stateDataBuf - Buffer containing the state data. + * @returns {Object} Decoded state data including moment and count. + */ static decodeReputationHostCountState(stateKeyBuf, stateDataBuf) { const keyOffset = STATE_KEY_SIZE - 8; const data = { @@ -212,6 +245,13 @@ class StateHelpers { return data; } + /** + * Decodes a host address state from buffers. + * + * @param {Buffer} stateKeyBuf - The buffer containing the state key. + * @param {Buffer} stateDataBuf - The buffer containing the state data. + * @returns {Object} The decoded host address state. + */ static decodeHostAddressState(stateKeyBuf, stateDataBuf) { let data = { address: codec.encodeAccountID(stateKeyBuf.slice(12)), @@ -247,6 +287,12 @@ class StateHelpers { return data; } + /** + * Decodes a token ID state from a buffer. + * + * @param {Buffer} stateDataBuf - The buffer containing the state data. + * @returns {Object} The decoded token ID state. + */ static decodeTokenIdState(stateDataBuf) { return { address: codec.encodeAccountID(stateDataBuf.slice(HOST_ADDRESS_OFFSET, HOST_CPU_MODEL_NAME_OFFSET)), @@ -261,6 +307,13 @@ class StateHelpers { } } + /** + * Decodes a transferee address state from buffers. + * + * @param {Buffer} stateKeyBuf - The buffer containing the state key. + * @param {Buffer} stateDataBuf - The buffer containing the state data. + * @returns {Object} The decoded transferee address state. + */ static decodeTransfereeAddrState(stateKeyBuf, stateDataBuf) { const prevHostClassicAddress = codec.encodeAccountID(stateDataBuf.slice(PREV_HOST_ADDRESS_OFFSET, TRANSFER_LEDGER_IDX_OFFSET)); return { @@ -272,6 +325,13 @@ class StateHelpers { } } + /** + * Decodes a candidate owner state from buffers. + * + * @param {Buffer} stateKeyBuf - The buffer containing the state key. + * @param {Buffer} stateDataBuf - The buffer containing the state data. + * @returns {Object} The decoded candidate owner state. + */ static decodeCandidateOwnerState(stateKeyBuf, stateDataBuf) { let data = { ownerAddress: codec.encodeAccountID(stateKeyBuf.slice(12)), @@ -285,6 +345,12 @@ class StateHelpers { return data; } + /** + * Decodes a candidate ID state from a buffer. + * + * @param {Buffer} stateDataBuf - The buffer containing the state data. + * @returns {Object} The decoded candidate ID state. + */ static decodeCandidateIdState(stateDataBuf) { let status = ''; switch (stateDataBuf.readUInt8(CANDIDATE_STATUS_OFFSET)) { @@ -319,6 +385,13 @@ class StateHelpers { } } + /** + * Decodes state data based on the state key and state data buffers. + * + * @param {Buffer} stateKey - The buffer containing the state key. + * @param {Buffer} stateData - The buffer containing the state data. + * @returns {Object} The decoded state data with type information. + */ static decodeStateData(stateKey, stateData) { const hexKey = stateKey.toString('hex').toUpperCase(); if (Buffer.from(HookStateKeys.PREFIX_HOST_ADDR, 'hex').compare(stateKey, 0, 4) === 0) { @@ -564,6 +637,13 @@ class StateHelpers { throw { type: 'Validation Error', message: 'Invalid state key.' }; } + /** + * Decodes a state key into a type and key. + * + * @param {Buffer} stateKey - The buffer containing the state key. + * @returns {Object} An object containing the key as a hexadecimal string and its type. + * @throws {Object} Throws a Validation Error if the state key is invalid. + */ static decodeStateKey(stateKey) { const hexKey = stateKey.toString('hex').toUpperCase(); if (Buffer.from(HookStateKeys.PREFIX_HOST_ADDR, 'hex').compare(stateKey, 0, 4) === 0) { @@ -633,6 +713,12 @@ class StateHelpers { throw { type: 'Validation Error', message: 'Invalid state key.' }; } + /** + * Generates a state key for a token ID. + * + * @param {string} uriToken - The URI token in hexadecimal format. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateTokenIdStateKey(uriToken) { // 1 byte - Key Type. let buf = Buffer.alloc(1, 0); @@ -643,6 +729,12 @@ class StateHelpers { return stateKeyBuf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a host address. + * + * @param {string} address - The host address. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateHostAddrStateKey(address) { // 1 byte - Key Type. // 8 bytes - Zeros. @@ -657,6 +749,12 @@ class StateHelpers { return stateKeyBuf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a reputation host address. + * + * @param {string} address - The reputation host address. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateReputationHostAddrStateKey(address) { const buf = Buffer.alloc(STATE_KEY_SIZE, 0); Buffer.from(codec.decodeAccountID(address), "hex").copy(buf, buf.length - ACCOUNT_ID_SIZE); @@ -664,6 +762,13 @@ class StateHelpers { return buf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a reputation host order address. + * + * @param {string} address - The reputation host address. + * @param {number} moment - The moment timestamp. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateReputationHostOrderAddressStateKey(address, moment) { const buf = Buffer.alloc(STATE_KEY_SIZE, 0); const offset = buf.length - ACCOUNT_ID_SIZE - 8; @@ -673,6 +778,13 @@ class StateHelpers { return buf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a reputation host ordered ID. + * + * @param {string} orderedId - The ordered ID. + * @param {number} moment - The moment timestamp. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateReputationHostOrderedIdStateKey(orderedId, moment) { let buf = Buffer.alloc(STATE_KEY_SIZE, 0); const offset = buf.length - 16; @@ -682,6 +794,12 @@ class StateHelpers { return buf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a reputation host count. + * + * @param {number} moment - The moment timestamp. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateReputationHostCountStateKey(moment) { let buf = Buffer.alloc(STATE_KEY_SIZE, 0); const offset = buf.length - 8; @@ -690,6 +808,12 @@ class StateHelpers { return buf.toString('hex').toUpperCase(); } + /** + * Generates a state key for reputation contract information. + * + * @param {string} address - The contract address. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateReputationContractInfoStateKey(address) { const buf = Buffer.alloc(STATE_KEY_SIZE, 0); Buffer.from(EVERNODE_PREFIX, "utf-8").copy(buf, 0); @@ -700,6 +824,12 @@ class StateHelpers { return buf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a transferee address. + * + * @param {string} address - The transferee address. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateTransfereeAddrStateKey(address) { // 1 byte - Key Type. // 8 bytes - Zeros. @@ -714,6 +844,12 @@ class StateHelpers { return stateKeyBuf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a candidate ID. + * + * @param {string} uniqueId - The unique candidate ID. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateCandidateIdStateKey(uniqueId) { // 1 byte - Key Type. let buf = Buffer.alloc(1, 0); @@ -724,6 +860,12 @@ class StateHelpers { return stateKeyBuf.toString('hex').toUpperCase(); } + /** + * Generates a state key for a candidate owner. + * + * @param {string} owner - The candidate owner address. + * @returns {string} The generated state key as a hexadecimal string. + */ static generateCandidateOwnerStateKey(owner) { // 1 byte - Key Type. // 8 bytes - Zeros. @@ -738,6 +880,14 @@ class StateHelpers { return stateKeyBuf.toString('hex').toUpperCase(); } + /** + * Gets the hook state index for a specific hook account and state key. + * + * @param {string} hookAccount - The hook account address. + * @param {string} stateKey - The state key as a hexadecimal string. + * @param {string} [hookNamespace=EvernodeConstants.HOOK_NAMESPACE] - The hook namespace. + * @returns {string} The hook state index as a hexadecimal string. + */ static getHookStateIndex(hookAccount, stateKey, hookNamespace = EvernodeConstants.HOOK_NAMESPACE) { const typeBuf = Buffer.alloc(2, 0); typeBuf.writeInt16BE(HOOK_STATE_LEDGER_TYPE_PREFIX); @@ -758,6 +908,12 @@ class StateHelpers { return digest.substring(0, 64).toUpperCase(); } + /** + * Generates a new hook candidate ID based on hash buffers. + * + * @param {Buffer} hashesBuf - The buffer containing the hash data. + * @returns {string} The generated candidate ID as a hexadecimal string. + */ static getNewHookCandidateId(hashesBuf) { const idBuf = Buffer.alloc(32, 0); idBuf.writeUInt8(EvernodeConstants.CandidateTypes.NewHook, 4); @@ -765,6 +921,11 @@ class StateHelpers { return idBuf.toString('hex').toUpperCase(); } + /** + * Generates a candidate ID for the piloted mode. + * + * @returns {string} The generated candidate ID as a hexadecimal string. + */ static getPilotedModeCandidateId() { const idBuf = Buffer.alloc(32, 0); idBuf.writeUInt8(EvernodeConstants.CandidateTypes.PilotedMode, 4); @@ -772,6 +933,12 @@ class StateHelpers { return idBuf.toString('hex').toUpperCase(); } + /** + * Generates a candidate ID for a dud host. + * + * @param {string} hostAddress - The host address. + * @returns {string} The generated candidate ID as a hexadecimal string. + */ static getDudHostCandidateId(hostAddress) { const idBuf = Buffer.alloc(32, 0); idBuf.writeUInt8(EvernodeConstants.CandidateTypes.DudHost, 4); @@ -779,6 +946,12 @@ class StateHelpers { return idBuf.toString('hex').toUpperCase(); } + /** + * Retrieves the candidate type from a candidate ID. + * + * @param {string} candidateId - The candidate ID as a hexadecimal string. + * @returns {number} The candidate type. + */ static getCandidateType(candidateId) { return Buffer.from(candidateId, 'hex').readUInt8(4); } diff --git a/src/transaction-helper.js b/src/transaction-helper.js index f40d9f8..fcba2cb 100644 --- a/src/transaction-helper.js +++ b/src/transaction-helper.js @@ -1,8 +1,16 @@ const { MemoFormats, HookParamKeys } = require('./evernode-common'); +/** + * Provides various utility functions for working with Xahau Transactions. + */ class TransactionHelper { - // Convert memos from our object type to xrpl lib object type. + /** + * Converts an array of memos from the internal format to the XRPL library format. + * + * @param {Array} memos - An array of memo objects in the internal format. + * @returns {Array} An array of memo objects in the XRPL library format. + */ static formatMemos(memos) { return memos ? memos.filter(m => m.type).map(m => { const data = (m.format === MemoFormats.HEX) ? m.data : @@ -17,7 +25,12 @@ class TransactionHelper { }) : []; } - // Convert memos from xrpl lib object type to our object type. + /** + * Converts an array of memos from the XRPL library format to the internal format. + * + * @param {Array} memos - An array of memo objects in the XRPL library format. + * @returns {Array} An array of memo objects in the internal format. + */ static deserializeMemos(memos) { if (!memos) return []; @@ -34,7 +47,12 @@ class TransactionHelper { }) } - // Convert hook params from our object type to xrpl lib object type. + /** + * Converts an array of hook parameters from the internal format to the XRPL library format. + * + * @param {Array} params - An array of hook parameter objects in the internal format. + * @returns {Array} An array of hook parameter objects in the XRPL library format. + */ static formatHookParams(params) { return params ? params.filter(m => m.name).map(m => { return { @@ -48,7 +66,12 @@ class TransactionHelper { }) : []; } - // Convert hook params from xrpl lib object type to our object type. + /** + * Converts an array of hook parameters from the XRPL library format to the internal format. + * + * @param {Array} params - An array of hook parameter objects in the XRPL library format. + * @returns {Array} An array of hook parameter objects in the internal format. + */ static deserializeHookParams(params) { if (!params) return []; @@ -63,6 +86,12 @@ class TransactionHelper { }) } + /** + * Converts a hexadecimal string to an ASCII string. + * + * @param {string} hex - The hexadecimal string to be converted. + * @returns {string} The resulting ASCII string. + */ static hexToASCII(hex) { if (!hex) return ""; @@ -70,6 +99,12 @@ class TransactionHelper { return Buffer.from(hex, 'hex').toString(); } + /** + * Converts an ASCII string to a hexadecimal string. + * + * @param {string} str - The ASCII string to be converted. + * @returns {string} The resulting hexadecimal string. + */ static asciiToHex(str) { if (!str) return ""; diff --git a/src/util-helpers.js b/src/util-helpers.js index 557e53f..cb00164 100644 --- a/src/util-helpers.js +++ b/src/util-helpers.js @@ -5,9 +5,17 @@ const { EvernodeConstants } = require('./evernode-common'); const { TransactionHelper } = require('./transaction-helper'); const { EvernodeHelpers } = require('./evernode-helpers'); -// Utility helper functions. +/** + * Provides utility helper functions for various operations. + */ class UtilHelpers { + /** + * Decodes a lease token URI into its integrant parts. + * + * @param {string} hexUri - The lease token URI in hexadecimal format. + * @returns {Object} An object containing the decoded lease token URI's version, leaseIndex, halfTos, leaseAmount, identifier, and outboundIP + */ static decodeLeaseTokenUri(hexUri) { // Get the lease index from the token's URI. // lease index 16)><(ip numeric array)> @@ -45,6 +53,12 @@ class UtilHelpers { } } + /** + * Gets the current Unix time. + * + * @param {string} [format="sec"] - The format of the time. If "sec", returns the time in seconds; otherwise, returns the time in milliseconds. + * @returns {number} The current Unix time in the specified format. + */ static getCurrentUnixTime(format = "sec") { const time = Date.now(); switch (format) { @@ -55,10 +69,22 @@ class UtilHelpers { } } + /** + * Derives a keypair from a given secret. + * + * @param {string} secret - The secret used to derive the keypair. + * @returns {Object} An object containing the derived keypair. + */ static deriveKeypair(secret) { return kp.deriveKeypair(secret); } + /** + * Derives an address from a given public key. + * + * @param {string} publicKey - The public key used to derive the address. + * @returns {string} The derived address. + */ static deriveAddress(publicKey) { return kp.deriveAddress(publicKey); } diff --git a/src/xfl-helpers.js b/src/xfl-helpers.js index 1ac39de..6a2ad9f 100644 --- a/src/xfl-helpers.js +++ b/src/xfl-helpers.js @@ -3,9 +3,18 @@ const maxMantissa = 9999999999999999n const minExponent = -96 const maxExponent = 80 -// Helper class to handle XFL float numbers. +/** + * Helper class for handling XFL (Extended Floating-Point) float numbers. + */ class XflHelpers { + /** + * Retrieves the exponent of the XFL float number. + * + * @param {bigint} xfl - The XFL float number. + * @returns {bigint} The exponent of the XFL float number. + * @throws {string} Throws an error if the XFL float number is negative. + */ static getExponent(xfl) { if (xfl < 0n) throw "Invalid XFL"; @@ -14,6 +23,13 @@ class XflHelpers { return ((xfl >> 54n) & 0xFFn) - 97n; } + /** + * Retrieves the mantissa of the XFL float number. + * + * @param {bigint} xfl - The XFL float number. + * @returns {bigint} The mantissa of the XFL float number. + * @throws {string} Throws an error if the XFL float number is negative. + */ static getMantissa(xfl) { if (xfl < 0n) throw "Invalid XFL"; @@ -22,6 +38,13 @@ class XflHelpers { return xfl - ((xfl >> 54n) << 54n); } + /** + * Checks if the XFL float number is negative. + * + * @param {bigint} xfl - The XFL float number. + * @returns {boolean} `true` if the XFL float number is negative, otherwise `false`. + * @throws {string} Throws an error if the XFL float number is negative. + */ static isNegative(xfl) { if (xfl < 0n) throw "Invalid XFL"; @@ -30,6 +53,13 @@ class XflHelpers { return ((xfl >> 62n) & 1n) == 0n; } + /** + * Converts an XFL float number to its string representation. + * + * @param {bigint} xfl - The XFL float number. + * @returns {string} The string representation of the XFL float number. + * @throws {string} Throws an error if the XFL float number is negative. + */ static toString(xfl) { if (xfl < 0n) throw "Invalid XFL"; @@ -56,6 +86,12 @@ class XflHelpers { return (this.isNegative(xfl) ? '-' : '') + finalResult.replace(/\.+$/, ''); } + /** + * Converts a string representation of a float number to an XFL float number. + * + * @param {string} floatStr - The string representation of the float number. + * @returns {bigint} The XFL float number. + */ static getXfl(floatStr) { let exponent; let mantissa; diff --git a/src/xrpl-account.js b/src/xrpl-account.js index 4f7c7e1..a4a4359 100644 --- a/src/xrpl-account.js +++ b/src/xrpl-account.js @@ -7,12 +7,21 @@ const { EventEmitter } = require('./event-emitter'); const { Defaults } = require('./defaults'); const { UtilHelpers } = require('./util-helpers'); +/** + * Represents an XRP Ledger account and provides methods for account management. + */ class XrplAccount { #events = new EventEmitter(); #subscribed = false; #txStreamHandler; + /** + * Constructs an XrplAccount instance. + * @param {string|null} address - The account address (optional). + * @param {string|null} secret - The secret key (optional). + * @param {Object} options - Additional options (optional). + */ constructor(address = null, secret = null, options = {}) { if (!address && !secret) throw "Both address and secret cannot be empty"; @@ -41,18 +50,38 @@ class XrplAccount { }; } + /** + * Adds an event listener for the specified event. + * @param {string} event - The name of the event. + * @param {Function} handler - The event handler function. + */ on(event, handler) { this.#events.on(event, handler); } + /** + * Adds a one-time event listener for the specified event. + * @param {string} event - The name of the event. + * @param {Function} handler - The event handler function. + */ once(event, handler) { this.#events.once(event, handler); } + /** + * Removes an event listener for the specified event. + * @param {string} event - The name of the event. + * @param {Function|null} handler - The event handler function (optional). + */ off(event, handler = null) { this.#events.off(event, handler); } + /** + * Derives the keypair from the account secret. + * @throws Will throw an error if the account secret is empty. + * @returns {Object} The derived keypair. + */ deriveKeypair() { if (!this.secret) throw 'Cannot derive key pair: Account secret is empty.'; @@ -60,39 +89,79 @@ class XrplAccount { return UtilHelpers.deriveKeypair(this.secret); } + + /** + * Checks if the account exists. + * @returns {Promise} True if the account exists, otherwise false. + */ async exists() { return await this.xrplApi.isAccountExists(this.address); } + /** + * Retrieves account information. + * @returns {Promise} The account information. + */ async getInfo() { return await this.xrplApi.getAccountInfo(this.address); } + /** + * Gets the account's sequence number. + * @returns {Promise} The account's sequence number. + */ async getSequence() { return (await this.getInfo())?.Sequence; } + /** + * Retrieves the number of NFTs minted by the account. + * @returns {Promise} The number of minted NFTs. + */ async getMintedNFTokens() { return ((await this.getInfo())?.MintedNFTokens || 0); } + /** + * Retrieves the number of NFTs burned by the account. + * @returns {number} The number of burned NFTs. + */ async getBurnedNFTokens() { return ((await this.getInfo())?.BurnedNFTokens || 0); } + /** + * Retrieves the account's message key. + * @returns {Promise} The message key or null if not set. + */ async getMessageKey() { return (await this.getInfo())?.MessageKey; } + /** + * Retrieves the wallet locator from the account info. + * @returns {Promise} The wallet locator or null if not found. + */ async getWalletLocator() { return (await this.getInfo())?.WalletLocator; } + + /** + * Retrieves the domain from the account info and converts it from hex to ASCII. + * @returns {Promise} The domain as ASCII or null if not found. + */ async getDomain() { const domain = (await this.getInfo())?.Domain; return domain ? TransactionHelper.hexToASCII(domain) : null; } + /** + * Retrieves the trust lines for the account, filtered by currency and issuer. + * @param {string} [currency] The currency to filter by. + * @param {string} issuer The issuer of the trust lines. + * @returns {Promise>} The list of trust lines, filtered if a currency is specified. + */ async getTrustLines(currency, issuer) { const lines = await this.xrplApi.getTrustlines(this.address, { limit: 399, @@ -101,55 +170,118 @@ class XrplAccount { return currency ? lines.filter(l => l.currency === currency) : lines; } + /** + * Retrieves the checks for the specified account. + * @param {string} fromAccount The account from which to retrieve checks. + * @returns {Promise>} The list of checks. + */ async getChecks(fromAccount) { return await this.xrplApi.getAccountObjects(fromAccount, { type: "check" }); } + /** + * Retrieves the NFTs for the account. + * @returns {Promise>} The list of NFTs. + */ async getNfts() { return await this.xrplApi.getNfts(this.address, { limit: 399 }); } + /** + * Retrieves the offers for the account. + * @returns {Promise>} The list of offers. + */ async getOffers() { return await this.xrplApi.getOffers(this.address); } + /** + * Retrieves the NFT offers for the account. + * @returns {Promise>} The list of NFT offers. + */ async getNftOffers() { return await this.xrplApi.getNftOffers(this.address); } + /** + * Retrieves a specific NFT by its URI. + * @param {string} uri The URI of the NFT to retrieve. + * @param {boolean} [isHexUri=false] Whether the URI is in hexadecimal format. + * @returns {Promise} The NFT object or null if not found. + */ async getNftByUri(uri, isHexUri = false) { const nfts = await this.getNfts(); const hexUri = isHexUri ? uri : TransactionHelper.asciiToHex(uri).toUpperCase(); return nfts.find(n => n.URI == hexUri); } + /** + * Retrieves account objects for the account with the specified options. + * @param {Object} options The options for retrieving account objects. + * @returns {Promise>} The list of account objects. + */ async getAccountObjects(options) { return await this.xrplApi.getAccountObjects(this.address, options); } + /** + * Retrieves namespace entries for the account. + * @param {string} namespaceId The ID of the namespace to retrieve entries for. + * @param {Object} [options={}] The options for retrieving namespace entries. + * @returns {Promise>} The list of namespace entries. + */ async getNamespaceEntries(namespaceId, options = {}) { return await this.xrplApi.getNamespaceEntries(this.address, namespaceId, options); } + /** + * Retrieves the flags set on the account. + * @returns {Promise} The account flags. + */ async getFlags() { return xrpl.parseAccountRootFlags((await this.getInfo()).Flags); } + /** + * Retrieves account transactions within a specified ledger range. + * @param {number} [minLedgerIndex=-1] The minimum ledger index to retrieve transactions from. + * @param {number} [maxLedgerIndex=-1] The maximum ledger index to retrieve transactions from. + * @param {boolean} [isForward=true] Whether to retrieve transactions in forward order. + * @returns {Promise} The list of transactions. + */ async getAccountTrx(minLedgerIndex = -1, maxLedgerIndex = -1, isForward = true) { return await this.xrplApi.getAccountTrx(this.address, { ledger_index_min: minLedgerIndex, ledger_index_max: maxLedgerIndex, forward: isForward }); } + /** + * Checks if the current wallet has a valid key pair for the account. + * @returns {Promise} True if the key pair is valid, otherwise false. + */ async hasValidKeyPair() { return await this.xrplApi.isValidKeyForAddress(this.wallet.publicKey, this.address); } + /** + * Sets account fields. + * @param {Object} fields - The fields to set. + * @param {Object} options - Additional transaction options (optional). + * @returns {Promise} The transaction result. + */ async setAccountFields(fields, options = {}) { const preparedTxn = await this.prepareSetAccountFields(fields, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } + /** + * Prepares an AccountSet transaction with the specified fields and options. + * @param {Object} fields The fields to set for the account. + * Example: { Domain: "www.mydomain.com", Flags: { asfDefaultRipple: false, asfDisableMaster: true } } + * @param {Object} [options={}] Additional options for the transaction. Can include hook parameters. + * @throws Will throw an error if no fields are provided and `allowEmptyAccountSet` is not true. + * @returns {Promise} The prepared AccountSet transaction. + */ async prepareSetAccountFields(fields, options = {}) { /** * Example for fields @@ -194,6 +326,12 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(tx, options); } + /** + * Sets the signer list for the account. + * @param {Array} signerList The list of signers to set for the account. + * @param {Object} [options={}] Additional options for setting the signer list. + * @returns {Promise} The result of the sign and submit operation. + */ async setSignerList(signerList = [], options = {}) { const preparedTxn = await this.prepareSetSignerList(signerList, options); @@ -204,7 +342,7 @@ class XrplAccount { * Set the signer list to the account. Setting signerQuorum = 0 in options, will remove the signerlist from the account. * @param {*} signerList (optional) An array of signers. Ex: [ {account:"ras24cvffvfbvfbbt5or4332", weight: 1}, {}, ...] * @param {*} options Ex: {signerQuorum: 1, sequence: 6543233} - * @returns a promise + * @returns {Promise} Prepared transaction. */ async prepareSetSignerList(signerList = [], options = {}) { if (options.signerQuorum < 0) @@ -241,11 +379,25 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(signerListTx, options); } + /** + * Invokes a transaction to a specified address. + * @param {string} toAddr The destination address. + * @param {Object|null} [blobObj=null] Optional blob object with data and its format. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async invoke(toAddr, blobObj = null, options = {}) { const preparedTxn = await this.prepareInvoke(toAddr, blobObj, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares an invoke transaction. + * @param {string} toAddr The destination address. + * @param {Object|null} [blobObj=null] Blob object containing data and whether it's in hex. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared invoke transaction. + */ async prepareInvoke(toAddr, blobObj = null, options = {}) { var txObj = { @@ -265,11 +417,31 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(txObj, options); } +/** + * Makes a payment to the specified address. + * @param {string} toAddr The destination address. + * @param {number|string} amount The amount to send. + * @param {string|null} [currency=null] Optional currency code. + * @param {string|null} [issuer=null] Optional issuer for non-XRP currencies. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async makePayment(toAddr, amount, currency = null, issuer = null, memos = null, options = {}) { const preparedTxn = await this.prepareMakePayment(toAddr, amount, currency, issuer, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares a payment transaction. + * @param {string} toAddr The destination address. + * @param {number|string} amount The amount to send. + * @param {string|null} [currency=null] Optional currency code. + * @param {string|null} [issuer=null] Optional issuer for non-XRP currencies. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared payment transaction. + */ async prepareMakePayment(toAddr, amount, currency = null, issuer = null, memos = null, options = {}) { const amountObj = makeAmountObject(amount, currency, issuer); @@ -284,11 +456,31 @@ class XrplAccount { }, options); } +/** + * Sets a trust line with the specified parameters. + * @param {string} currency The currency code for the trust line. + * @param {string} issuer The issuer of the currency. + * @param {string} limit The limit for the trust line. + * @param {boolean} [allowRippling=false] Whether to allow rippling. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async setTrustLine(currency, issuer, limit, allowRippling = false, memos = null, options = {}) { const preparedTxn = await this.prepareSetTrustLine(currency, issuer, limit, allowRippling, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares a trust line transaction. + * @param {string} currency The currency code for the trust line. + * @param {string} issuer The issuer of the currency. + * @param {string} limit The limit for the trust line. + * @param {boolean} [allowRippling=false] Whether to allow rippling. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared trust line transaction. + */ async prepareSetTrustLine(currency, issuer, limit, allowRippling = false, memos = null, options = {}) { if (typeof limit !== 'string') @@ -312,11 +504,25 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(tx, options); } +/** + * Sets the regular key for the account. + * @param {string} regularKey The regular key to set. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async setRegularKey(regularKey, memos = null, options = {}) { const preparedTxn = await this.prepareSetRegularKey(regularKey, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares a transaction to set the regular key for the account. + * @param {string} regularKey The regular key to set. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared regular key transaction. + */ async prepareSetRegularKey(regularKey, memos = null, options = {}) { return await this.#prepareSubmissionTransaction({ @@ -333,6 +539,12 @@ class XrplAccount { return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Cashes a check for the account. + * @param {Object} check The check object with details. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async prepareCashCheck(check, options = {}) { const checkIDhasher = crypto.createHash('sha512') checkIDhasher.update(Buffer.from('0043', 'hex')) @@ -355,11 +567,38 @@ class XrplAccount { }, options); } +/** + * Creates an offer to sell assets. + * @param {number|string} sellAmount The amount to sell. + * @param {string} sellCurrency The currency code of the asset to sell. + * @param {string} sellIssuer The issuer of the asset to sell. + * @param {number|string} forAmount The amount to receive. + * @param {string} forCurrency The currency code of the asset to receive. + * @param {string|null} [forIssuer=null] The issuer of the asset to receive. + * @param {number} [expiration=4294967295] The expiration time for the offer. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async offerSell(sellAmount, sellCurrency, sellIssuer, forAmount, forCurrency, forIssuer = null, expiration = 4294967295, memos = null, options = {}) { const preparedTxn = await this.prepareOfferSell(sellAmount, sellCurrency, sellIssuer, forAmount, forCurrency, forIssuer, expiration, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } + +/** + * Prepares a transaction to sell assets. + * @param {number|string} sellAmount The amount to sell. + * @param {string} sellCurrency The currency code of the asset to sell. + * @param {string} sellIssuer The issuer of the asset to sell. + * @param {number|string} forAmount The amount to receive. + * @param {string} forCurrency The currency code of the asset to receive. + * @param {string|null} [forIssuer=null] The issuer of the asset to receive. + * @param {number} [expiration=4294967295] The expiration time for the offer. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared offer sell transaction. + */ async prepareOfferSell(sellAmount, sellCurrency, sellIssuer, forAmount, forCurrency, forIssuer = null, expiration = 4294967295, memos = null, options = {}) { const sellAmountObj = makeAmountObject(sellAmount, sellCurrency, sellIssuer); @@ -376,11 +615,37 @@ class XrplAccount { }, options); } +/** + * Creates an offer to buy assets. + * @param {number|string} buyAmount The amount to buy. + * @param {string} buyCurrency The currency code of the asset to buy. + * @param {string} buyIssuer The issuer of the asset to buy. + * @param {number|string} forAmount The amount to give in exchange. + * @param {string} forCurrency The currency code of the asset to give in exchange. + * @param {string|null} [forIssuer=null] The issuer of the asset to give in exchange. + * @param {number} [expiration=4294967295] The expiration time for the offer. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async offerBuy(buyAmount, buyCurrency, buyIssuer, forAmount, forCurrency, forIssuer = null, expiration = 4294967295, memos = null, options = {}) { const preparedTxn = await this.prepareOfferBuy(buyAmount, buyCurrency, buyIssuer, forAmount, forCurrency, forIssuer, expiration, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares an offer to buy assets. + * @param {number|string} buyAmount The amount to buy. + * @param {string} buyCurrency The currency code of the asset to buy. + * @param {string} buyIssuer The issuer of the asset to buy. + * @param {number|string} forAmount The amount to give in exchange. + * @param {string} forCurrency The currency code of the asset to give in exchange. + * @param {string|null} [forIssuer=null] The issuer of the asset to give in exchange. + * @param {number} [expiration=4294967295] The expiration time for the offer. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared offer buy transaction. + */ async prepareOfferBuy(buyAmount, buyCurrency, buyIssuer, forAmount, forCurrency, forIssuer = null, expiration = 4294967295, memos = null, options = {}) { const buyAmountObj = makeAmountObject(buyAmount, buyCurrency, buyIssuer); @@ -397,11 +662,25 @@ class XrplAccount { }, options); } +/** + * Cancels an existing offer. + * @param {number} offerSequence The sequence number of the offer to cancel. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The result of the sign and submit operation. + */ async cancelOffer(offerSequence, memos = null, options = {}) { const preparedTxn = await this.prepareCancelOffer(offerSequence, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares a transaction to cancel an offer. + * @param {number} offerSequence The sequence number of the offer to cancel. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared offer cancel transaction. + */ async prepareCancelOffer(offerSequence, memos = null, options = {}) { return await this.#prepareSubmissionTransaction({ TransactionType: XrplTransactionTypes.OFFER_CANCEL, @@ -548,6 +827,11 @@ class XrplAccount { } } +/** + * Subscribes to the XRPL address stream for transaction updates. + * Ensures only one subscription is active at a time. + * @returns {Promise} + */ async subscribe() { // Subscribe only once. Otherwise event handlers will be duplicated. if (this.#subscribed) @@ -558,6 +842,10 @@ class XrplAccount { this.#subscribed = true; } +/** + * Unsubscribes from the XRPL address stream. + * @returns {Promise} + */ async unsubscribe() { if (!this.#subscribed) return; @@ -566,10 +854,11 @@ class XrplAccount { this.#subscribed = false; } - /** - * Submit the signed raw transaction. - * @param txBlob Signed and encoded transacion as a hex string. - */ +/** + * Submits a signed raw transaction. + * @param {string} txBlob Signed and encoded transaction as a hex string. + * @returns {Promise} Result of the transaction submission. + */ submitTransactionBlob(txBlob) { // Returned format. @@ -611,23 +900,39 @@ class XrplAccount { }); } - /** - * Sign the given transaction and returns the signed blob and its hash. - * @param {object} tx Transaction object. - * @param {boolean} isMultiSign Whether the transaction is for multisigning. Defaults to false. - * @returns {hash: string, tx_blob: string} - */ +/** + * Signs the given transaction and returns the signed blob and its hash. + * @param {Object} tx Transaction object. + * @param {boolean} [isMultiSign=false] Whether the transaction is for multisigning. + * @returns {Object} The signed transaction hash and blob. Format: {hash: string, tx_blob: string} + */ sign(tx, isMultiSign = false) { return this.xrplApi.xrplHelper.sign(tx, this.secret, isMultiSign) } // URIToken related methods +/** + * Mints a URI token. + * @param {string} uri The URI to mint as a token. + * @param {string|null} [digest=null] The optional digest for the token. + * @param {Object} [flags={}] Flags to control token properties (e.g., isBurnable). + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} Result of the mint transaction. + */ async mintURIToken(uri, digest = null, flags = {}, options = {}) { const preparedTxn = await this.prepareMintURIToken(uri, digest, flags, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares the minting of a URI token. + * @param {string} uri The URI to mint as a token. + * @param {string|null} [digest=null] The optional digest for the token. + * @param {Object} [flags={}] Flags to control token properties. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared mint transaction. + */ async prepareMintURIToken(uri, digest = null, flags = {}, options = {}) { const tx = { Account: this.address, @@ -642,12 +947,23 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(tx, options); } - +/** + * Burns a URI token. + * @param {string} uriTokenID The ID of the URI token to burn. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} Result of the burn transaction. + */ async burnURIToken(uriTokenID, options = {}) { const preparedTxn = await this.prepareBurnURIToken(uriTokenID, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares the burning of a URI token. + * @param {string} uriTokenID The ID of the URI token to burn. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared burn transaction. + */ async prepareBurnURIToken(uriTokenID, options = {}) { const tx = { Account: this.address, @@ -657,11 +973,33 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(tx, options); } +/** + * Creates a sell offer for a URI token. + * @param {string} uriTokenID The ID of the URI token to sell. + * @param {string|number} amount The amount to sell the token for. + * @param {string} currency The currency code for the sale. + * @param {string|null} [issuer=null] The issuer of the currency. + * @param {string|null} [toAddr=null] The address of the buyer. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} Result of the sell transaction. + */ async sellURIToken(uriTokenID, amount, currency, issuer = null, toAddr = null, memos = null, options = {}) { const preparedTxn = await this.prepareSellURIToken(uriTokenID, amount, currency, issuer, toAddr, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares a sell offer for a URI token. + * @param {string} uriTokenID The ID of the URI token to sell. + * @param {string|number} amount The amount to sell the token for. + * @param {string} currency The currency code for the sale. + * @param {string|null} [issuer=null] The issuer of the currency. + * @param {string|null} [toAddr=null] The address of the buyer. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared sell offer transaction. + */ async prepareSellURIToken(uriTokenID, amount, currency, issuer = null, toAddr = null, memos = null, options = {}) { const amountObj = makeAmountObject(amount, currency, issuer); const tx = { @@ -683,11 +1021,25 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(tx, options); } +/** + * Buys a URI token. + * @param {Object} uriToken The URI token object to buy. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} Result of the buy transaction. + */ async buyURIToken(uriToken, memos = null, options = {}) { const preparedTxn = await this.prepareBuyURIToken(uriToken, memos, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares a buy offer for a URI token. + * @param {Object} uriToken The URI token object to buy. + * @param {Array|null} [memos=null] Optional memos to attach to the transaction. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared buy offer transaction. + */ async prepareBuyURIToken(uriToken, memos = null, options = {}) { const tx = { Account: this.address, @@ -705,11 +1057,23 @@ class XrplAccount { return await this.#prepareSubmissionTransaction(tx, options); } +/** + * Clears a sell offer for a URI token. + * @param {string} uriTokenID The ID of the URI token offer to clear. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} Result of the clear offer transaction. + */ async clearURITokenOffer(uriTokenID, options = {}) { const preparedTxn = await this.prepareClearURITokenOffer(uriTokenID, options); return await this.signAndSubmit(preparedTxn, options.submissionRef); } +/** + * Prepares the clearing of a sell offer for a URI token. + * @param {string} uriTokenID The ID of the URI token offer to clear. + * @param {Object} [options={}] Additional options for the transaction. + * @returns {Promise} The prepared clear offer transaction. + */ async prepareClearURITokenOffer(uriTokenID, options = {}) { return await this.#prepareSubmissionTransaction({ Account: this.address, @@ -718,17 +1082,33 @@ class XrplAccount { }, options); } +/** + * Retrieves all URI tokens associated with the account. + * @param {Object} options Additional options for the retrieval. + * @returns {Promise} List of URI tokens. + */ async getURITokens(options) { const obj = await this.getAccountObjects(options); return obj.filter(t => t.LedgerEntryType == 'URIToken'); } +/** + * Retrieves a URI token by its URI. + * @param {string} uri The URI of the token to retrieve. + * @param {boolean} [isHexUri=false] Whether the URI is in hex format. + * @returns {Promise} The URI token object. + */ async getURITokenByUri(uri, isHexUri = false) { const index = this.generateIssuedURITokenId(uri, isHexUri); return await this.xrplApi.getURITokenByIndex(index); } - +/** + * Generates the issued URI token ID from a given URI. + * @param {string} uri The URI to generate the token ID from. + * @param {boolean} [isHexUri=false] Whether the URI is in hex format. + * @returns {string} The generated URI token ID. + */ generateIssuedURITokenId(uri, isHexUri = false) { if (uri.length < 1 || uri.length > 256) throw 'Invalid URI'; @@ -758,7 +1138,7 @@ class XrplAccount { * Prepare a transaction for submission. (Signing Free) * @param {object} tx Partially prepared transaction. * @param {*} options Options regarding to the transaction submission. - * @returns Submission transaction. + * @returns {Promise} Submission transaction. */ async #prepareSubmissionTransaction(tx, options) { // Attach tx options to the transaction. @@ -785,7 +1165,7 @@ class XrplAccount { * Sign and submit prepared transaction. * @param {object} preparedTransaction Prepared transaction. * @param {object} submissionRef [Optional] Reference object to take submission references. - * @returns result of the submitted transaction. + * @returns {Promise} result of the submitted transaction. */ async signAndSubmit(preparedTransaction, submissionRef = {}) { const signedTxn = this.sign(preparedTransaction, false); @@ -795,7 +1175,7 @@ class XrplAccount { /** * Submit a multi-singed transaction. * @param {object} tx Signed transaction. - * @returns Result of the transaction. + * @returns {Promise} Result of the transaction. */ async submitMultisigned(tx) { return await this.xrplApi.submitMultisigned(tx) diff --git a/src/xrpl-api.js b/src/xrpl-api.js index a539ce6..6c5e1b7 100644 --- a/src/xrpl-api.js +++ b/src/xrpl-api.js @@ -25,6 +25,9 @@ const NETWORK_MODES = { const FUNCTIONING_SERVER_STATES = ['full', 'validating', 'proposing'] const LEDGER_DESYNC_TIME = 20000 +/** + * Class representing an XRPL API client. + */ class XrplApi { #primaryServer; @@ -40,6 +43,13 @@ class XrplApi { #xrplClientOptions; #autoReconnect; + /** + * @param {string|null} rippledServer - The URL of the primary rippled server or null if not used. + * @param {Object} [options={}] - Optional configuration options. + * @param {Array} [options.fallbackRippledServers=[]] - List of fallback server URLs. + * @param {Object} [options.xrplClientOptions={}] - Options for the xrpl client. + * @param {boolean} [options.autoReconnect=true] - Whether to automatically reconnect. + */ constructor(rippledServer = null, options = {}) { if (rippledServer == '-') { this.#primaryServer = null; @@ -385,14 +395,29 @@ class XrplApi { } } + /** + * Adds an event listener for a specified event. + * @param {string} event - The event to listen for. + * @param {Function} handler - The function to call when the event occurs. + */ on(event, handler) { this.#events.on(event, handler); } + /** + * Adds a one-time event listener for a specified event. + * @param {string} event - The event to listen for. + * @param {Function} handler - The function to call when the event occurs. + */ once(event, handler) { this.#events.once(event, handler); } + /** + * Removes an event listener for a specified event. + * @param {string} event - The event to stop listening for. + * @param {Function} [handler=null] - The function to remove or null to remove all handlers. + */ off(event, handler = null) { this.#events.off(event, handler); } @@ -404,6 +429,10 @@ class XrplApi { return true; } + /** + * Connects to the XRPL API. + * @returns {Promise} + */ async connect() { this.#isPermanentlyDisconnected = false; @@ -414,6 +443,10 @@ class XrplApi { this.xrplHelper = new XrplHelpers(definitions.result); } + /** + * Disconnects from the XRPL API. + * @returns {Promise} + */ async disconnect() { await this.#acquireConnection(); @@ -445,6 +478,12 @@ class XrplApi { } } + /** + * Checks if the given public key is valid for the specified address. + * @param {string} publicKey - The public key to check. + * @param {string} address - The address to check against. + * @returns {Promise} Returns true if the public key is valid for the address. + */ async isValidKeyForAddress(publicKey, address) { const info = await this.getAccountInfo(address); const accountFlags = xrpl.parseAccountRootFlags(info.Flags); @@ -459,6 +498,11 @@ class XrplApi { return derivedPubKeyAddress === address || (regularKey && derivedPubKeyAddress === regularKey); } + /** + * Checks if an account exists at the specified address. + * @param {string} address - The account address. + * @returns {Promise} Returns true if the account exists. + */ async isAccountExists(address) { try { await this.#handleClientRequest({ command: 'account_info', account: address }); @@ -470,64 +514,143 @@ class XrplApi { } } + /** + * Gets the server state at the specified ledger index. + * @param {string} [ledgerIdx="current"] - The ledger index to get the state for. + * @returns {Promise} The server state. + */ async getServerState(ledgerIdx = "current") { const resp = (await this.#handleClientRequest({ command: 'server_state', ledger_index: ledgerIdx })); return resp?.result?.state?.server_state; } + /** + * Gets account information for a specified address. + * @param {string} address - The account address. + * @returns {Promise} The account information. + */ async getAccountInfo(address) { const resp = (await this.#handleClientRequest({ command: 'account_info', account: address })); return resp?.result?.account_data; } + /** + * Gets the server definitions. + * @returns {Promise} The server definitions. + */ async getServerDefinition() { const resp = (await this.#handleClientRequest({ command: 'server_definitions' })); return resp?.result; } + /** + * Gets information about the server. + * @returns {Promise} The server information. + */ async getServerInfo() { const resp = (await this.#handleClientRequest({ command: 'server_info' })); return resp?.result; } + /** + * Gets account objects for a specified address. + * @param {string} address - The account address. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The account objects. + */ async getAccountObjects(address, options) { return this.#requestWithPaging({ command: 'account_objects', account: address, ...options }, API_REQ_TYPE.ACCOUNT_OBJECTS); } + /** + * Gets namespace entries for a specified address and namespace ID. + * @param {string} address - The account address. + * @param {string} namespaceId - The namespace ID. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The namespace entries. + */ async getNamespaceEntries(address, namespaceId, options) { return this.#requestWithPaging({ command: 'account_namespace', account: address, namespace_id: namespaceId, ...options }, API_REQ_TYPE.NAMESPACE_ENTRIES); } + /** + * Gets NFT offers for a specified address. + * @param {string} address - The account address. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The NFT offers. + */ async getNftOffers(address, options) { const offers = await this.getAccountObjects(address, options); // TODO: Pass rippled filter parameter when xrpl.js supports it. return offers.filter(o => o.LedgerEntryType == 'NFTokenOffer'); } + /** + * Gets trustlines for a specified address. + * @param {string} address - The account address. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The trustlines. + */ async getTrustlines(address, options) { return this.#requestWithPaging({ command: 'account_lines', account: address, ledger_index: "validated", ...options }, API_REQ_TYPE.LINES); } + /** + * Gets account transactions for a specified address. + * @param {string} address - The account address. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The account transactions. + */ async getAccountTrx(address, options) { return this.#requestWithPaging({ command: 'account_tx', account: address, ...options }, API_REQ_TYPE.TRANSACTIONS); } + /** + * Gets NFTs for a specified address. + * @param {string} address - The account address. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The NFTs. + */ async getNfts(address, options) { return this.#requestWithPaging({ command: 'account_nfts', account: address, ledger_index: "validated", ...options }, API_REQ_TYPE.ACCOUNT_NFTS); } + /** + * Gets offers for a specified address. + * @param {string} address - The account address. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The offers. + */ async getOffers(address, options) { return this.#requestWithPaging({ command: 'account_offers', account: address, ledger_index: "validated", ...options }, API_REQ_TYPE.OFFERS); } + /** + * Gets sell offers for a specified NFT token ID. + * @param {string} nfTokenId - The NFT token ID. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The sell offers. + */ async getSellOffers(nfTokenId, options = {}) { return this.#requestWithPaging({ command: 'nft_sell_offers', nft_id: nfTokenId, ledger_index: "validated", ...options }, API_REQ_TYPE.OFFERS); } + /** + * Gets buy offers for a specified NFT token ID. + * @param {string} nfTokenId - The NFT token ID. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise>} The buy offers. + */ async getBuyOffers(nfTokenId, options = {}) { return this.#requestWithPaging({ command: 'nft_buy_offers', nft_id: nfTokenId, ledger_index: "validated", ...options }, API_REQ_TYPE.OFFERS); } + /** + * Gets ledger entry by index. + * @param {string} index - The ledger index. + * @param {Object} [options={}] - Optional parameters for the request. + * @returns {Promise} The ledger entry or null if not found. + */ async getLedgerEntry(index, options) { try { const resp = (await this.#handleClientRequest({ command: 'ledger_entry', index: index, ledger_index: "validated", ...options })); @@ -540,6 +663,11 @@ class XrplApi { } } + /** + * Gets the URI token by index. + * @param {string} index - The index of the URI token. + * @returns {Promise} The URI token entry or null if not found. + */ async getURITokenByIndex(index) { const entry = await this.getLedgerEntry(index); if (!entry || entry.LedgerEntryType !== 'URIToken') @@ -547,16 +675,34 @@ class XrplApi { return entry; } + /** + * Gets transaction information. + * @param {string} txnHash - The hash of the transaction. + * @param {Object} options - Optional parameters for the request. + * @returns {Promise} The transaction information. + */ async getTxnInfo(txnHash, options) { const resp = (await this.#handleClientRequest({ command: 'tx', transaction: txnHash, binary: false, ...options })); return resp?.result; } + /** + * Subscribes to address updates. + * @param {string} address - The address to subscribe to. + * @param {Function} handler - The handler function for address updates. + * @returns {Promise} + */ async subscribeToAddress(address, handler) { this.#addressSubscriptions.push({ address: address, handler: handler }); await this.#handleClientRequest({ command: 'subscribe', accounts: [address] }); } + /** + * Unsubscribes from address updates. + * @param {string} address - The address to unsubscribe from. + * @param {Function} handler - The handler function to remove. + * @returns {Promise} + */ async unsubscribeFromAddress(address, handler) { for (let i = this.#addressSubscriptions.length - 1; i >= 0; i--) { const sub = this.#addressSubscriptions[i]; @@ -566,6 +712,11 @@ class XrplApi { await this.#handleClientRequest({ command: 'unsubscribe', accounts: [address] }); } + /** + * Gets the transaction fee. + * @param {string} txBlob - The transaction blob. + * @returns {Promise} The transaction fee. + */ async getTransactionFee(txBlob) { const fees = await this.#handleClientRequest({ command: 'fee', tx_blob: txBlob }); return fees?.result?.drops?.base_fee; @@ -577,7 +728,7 @@ class XrplApi { /** * Get the transaction results if validated. - * @param {string} txHash Hash of the transaction to check. + * @param {string} txHash - Hash of the transaction to check. * @returns Validated results of the transaction. */ async getTransactionValidatedResults(txHash) { @@ -599,9 +750,9 @@ class XrplApi { /** * Watching to acquire the transaction submission. (Waits until txn. is applied to the ledger.) - * @param {string} txHash Transaction Hash - * @param {number} lastLedger Last ledger sequence of the transaction. - * @param {object} submissionResult Result of the submission. + * @param {string} txHash - Transaction Hash + * @param {number} lastLedger - Last ledger sequence of the transaction. + * @param {object} submissionResult - Result of the submission. * @returns Returns the applied transaction object. */ async #waitForFinalTransactionOutcome(txHash, lastLedger, submissionResult) { @@ -641,8 +792,8 @@ class XrplApi { /** * Arrange the transaction result to a standard format. - * @param {object} tx Submitted Transaction - * @param {object} submissionResult Response related to that transaction. + * @param {object} tx - Submitted Transaction + * @param {object} submissionResult - Response related to that transaction. * @returns prepared response of the transaction result. */ async #prepareResponse(tx, submissionResult) { @@ -669,8 +820,8 @@ class XrplApi { /** * Submit a multi-signature transaction and wait for validation. - * @param {object} tx Multi-signed transaction object. - * @param {object} submissionRef [Optional] Reference object to take submission references. + * @param {object} tx - Multi-signed transaction object. + * @param {object} submissionRef - [Optional] Reference object to take submission references. * @returns response object of the validated transaction. */ async submitMultisignedAndWait(tx, submissionRef = {}) { @@ -681,7 +832,7 @@ class XrplApi { /** * Only submit a multi-signature transaction. - * @param {object} tx Multi-signed transaction object. + * @param {object} tx - Multi-signed transaction object. * @returns response object of the submitted transaction. */ async submitMultisigned(tx) { @@ -691,8 +842,8 @@ class XrplApi { /** * Submit a single-signature transaction. - * @param {string} tx_blob Signed transaction object. - * @param {object} submissionRef [Optional] Reference object to take submission references. + * @param {string} tx_blob - Signed transaction object. + * @param {object} submissionRef - [Optional] Reference object to take submission references. * @returns response object of the validated transaction. */ async submitAndWait(tx, tx_blob, submissionRef = {}) { @@ -702,7 +853,7 @@ class XrplApi { /** * Only submit a single-signature transaction. - * @param {string} tx_blob Signed transaction object. + * @param {string} tx_blob - Signed transaction object. * @returns response object of the submitted transaction. */ async submit(tx_blob) { @@ -710,11 +861,12 @@ class XrplApi { } /** - * Join the given the array of signed transactions into one multi-signed transaction. - * For more details: https://js.xrpl.org/functions/multisign.html + * Joins the given array of signed transactions into one multi-signed transaction. + * For more details: https://js.xrpl.org/functions/multisign.html * - * @param {(string | Transaction)[]} transactions An array of signed Transactions (in object or blob form) to combine into a single signed Transaction. - * @returns A single signed Transaction string which has all Signers from transactions within it. + * @param {Array} transactions - An array of signed transactions, either as serialized strings or transaction objects, to combine into a single multi-signed transaction. + * @returns {string} A single multi-signed transaction in string format that contains all signers from the input transactions. + * @throws {Error} If the transactions array is empty. */ multiSign(transactions) { if (transactions.length > 0) { From d60101f98efe98e501f933926cd5894505e6f128 Mon Sep 17 00:00:00 2001 From: Dulana Peiris Date: Thu, 26 Sep 2024 10:30:16 +0530 Subject: [PATCH 2/4] Minor changes --- docs/init-docs.js | 4 +--- package.json | 1 + src/clients/base-evernode-client.js | 1 - src/clients/foundation-client.js | 2 -- src/clients/host-client.js | 1 - src/clients/tenant-client.js | 3 --- src/encryption-helper.js | 2 -- src/evernode-helpers.js | 7 ------- src/xfl-helpers.js | 5 ----- 9 files changed, 2 insertions(+), 24 deletions(-) diff --git a/docs/init-docs.js b/docs/init-docs.js index 7bc4516..cb82469 100644 --- a/docs/init-docs.js +++ b/docs/init-docs.js @@ -33,12 +33,10 @@ const updateJSDocUtil = () => { if (utilFileContent.includes(oldUtilFunction)) { utilFileContent = utilFileContent.replace(oldUtilFunction, newUtilFunction); fs.writeFileSync(jsdocUtilDumperPath, utilFileContent, 'utf8'); - console.log('JSDoc utility function modified successful!'); + console.log('JSDoc utility function modified successfully!'); } else { console.log('JSDoc obsolete utility function is not found.'); } }; - - updateJSDocUtil(); diff --git a/package.json b/package.json index d466117..9535a04 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "build": "npm run lint && ncc build src/index.js -e elliptic -e xrpl -e ripple-address-codec -e ripple-binary-codec -e ripple-keypairs -o dist/ && cp evernode-license.pdf dist/", "bundle": "npm run build && ./clean-pkg.sh", "publish": "npm run bundle && cp npm-readme.md dist/README.md && npm publish ./dist", + "docs-init": "node docs/init-docs.js", "docs": "echo '# Evernode JS API Documentation' > docs/evernode-js-api.md && xargs jsdoc2md < docs/filelist >> docs/evernode-js-api.md" }, "dependencies": { diff --git a/src/clients/base-evernode-client.js b/src/clients/base-evernode-client.js index 0963641..eef922f 100644 --- a/src/clients/base-evernode-client.js +++ b/src/clients/base-evernode-client.js @@ -32,7 +32,6 @@ const HOST_DEREG_FROM_REP_PARAM_SIZE = 53; /** * Creates an instance of BaseEvernodeClient. - * * @param {string} xrpAddress - The XRP address associated with the client. * @param {string} xrpSecret - The XRP secret associated with the client. * @param {Array} watchEvents - An array of event names to watch. diff --git a/src/clients/foundation-client.js b/src/clients/foundation-client.js index b0ec00d..ab009a1 100644 --- a/src/clients/foundation-client.js +++ b/src/clients/foundation-client.js @@ -18,14 +18,12 @@ const FoundationEvents = {} /** * FoundationClient class to manage and interact with foundation operations. * It extends the BaseEvernodeClient. - * * @extends BaseEvernodeClient */ class FoundationClient extends BaseEvernodeClient { /** * Creates an instance of FoundationClient. - * * @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 FoundationClient. diff --git a/src/clients/host-client.js b/src/clients/host-client.js index e2a7553..500c347 100644 --- a/src/clients/host-client.js +++ b/src/clients/host-client.js @@ -67,7 +67,6 @@ const TX_RETRY_INTERVAL = 10000; /** * HostClient class to manage host operations. * It extends the BaseEvernodeClient. - * * @extends BaseEvernodeClient */ class HostClient extends BaseEvernodeClient { diff --git a/src/clients/tenant-client.js b/src/clients/tenant-client.js index aac15f5..0d64b9b 100644 --- a/src/clients/tenant-client.js +++ b/src/clients/tenant-client.js @@ -20,14 +20,12 @@ const TenantEvents = { /** * TenantClient class to manage tenant operations. * It extends the BaseEvernodeClient. - * * @extends BaseEvernodeClient */ 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. @@ -52,7 +50,6 @@ class TenantClient extends BaseEvernodeClient { /** * Retrieves and validates a lease host based on the given host address. - * * @param {string} hostAddress - The XRP Ledger address of the host. * @returns {Promise} - Returns the host object if valid and active. * @throws Will throw an error if the host is invalid, inactive, or not registered. diff --git a/src/encryption-helper.js b/src/encryption-helper.js index 4956a0e..63de663 100644 --- a/src/encryption-helper.js +++ b/src/encryption-helper.js @@ -79,7 +79,6 @@ class EncryptionHelper { /** * Encrypts a message using the given public key. - * * @param {string} publicKey - The public key to use for encryption. * @param {Object} message - The message object to be encrypted. * @param {Object} [options={}] - Optional encryption parameters. @@ -95,7 +94,6 @@ class EncryptionHelper { /** * Decrypts an encrypted message using the given private key. - * * @param {string} privateKey - The private key to use for decryption. * @param {string} encrypted - The encrypted message string. * @returns {Promise} A promise that resolves to the decrypted message as an object, or null if decryption fails. diff --git a/src/evernode-helpers.js b/src/evernode-helpers.js index fa7b5b8..f45fe86 100644 --- a/src/evernode-helpers.js +++ b/src/evernode-helpers.js @@ -10,7 +10,6 @@ const NFT_PAGE_LEDGER_ENTRY_TYPE_HEX = '0050'; class EvernodeHelpers { /** * Retrieves URI tokens that are valid leases for the specified XRPL account. - * * @param {Object} xrplAcc - The XRPL account object. * @returns {Promise>} A promise that resolves to an array of URI tokens that are valid leases. */ @@ -21,7 +20,6 @@ class EvernodeHelpers { /** * Retrieves a lease by its index from the XRPL ledger. - * * @param {XrplApi} xrplApi - The XRPL API object. * @param {string} index - The ledger entry index. * @returns {Promise} A promise that resolves to the lease entry or null if not found or invalid. @@ -35,7 +33,6 @@ class EvernodeHelpers { /** * Retrieves all leases that have offers (i.e., an associated amount) for the specified XRPL account. - * * @param {Object} xrplAcc - The XRPL account object. * @returns {Promise>} A promise that resolves to an array of URI tokens with offers. */ @@ -46,7 +43,6 @@ class EvernodeHelpers { /** * Retrieves leases that do not have offers (i.e., no amount associated) for the specified XRPL account. - * * @param {Object} xrplAcc - The XRPL account object. * @returns {Promise>} A promise that resolves to an array of unoffered URI tokens. */ @@ -57,7 +53,6 @@ class EvernodeHelpers { /** * Finds the NFT page and location of a specific NFToken in the XRPL ledger. - * * @param {string} nfTokenId - The ID of the NFToken. * @param {Object} xrplAcc - The XRPL account object. * @param {Object} xrplApi - The XRPL API object. @@ -96,7 +91,6 @@ class EvernodeHelpers { /** * Calculates the reward quota for a specific epoch. - * * @param {number} epoch - The epoch number. * @param {number} firstEpochRewardQuota - The reward quota for the first epoch. * @returns {number} The calculated reward quota for the specified epoch. @@ -108,7 +102,6 @@ class EvernodeHelpers { /** * Checks if a given URI is valid based on a pattern and token category. - * * @param {string} uri - The URI to validate. * @param {string} pattern - The pattern to match the URI against. * @param {string} [tokenCategory=URITokenTypes.LEASE_URI_TOKEN] - The token category (default is a lease URI token). diff --git a/src/xfl-helpers.js b/src/xfl-helpers.js index 6a2ad9f..963a73e 100644 --- a/src/xfl-helpers.js +++ b/src/xfl-helpers.js @@ -10,7 +10,6 @@ class XflHelpers { /** * Retrieves the exponent of the XFL float number. - * * @param {bigint} xfl - The XFL float number. * @returns {bigint} The exponent of the XFL float number. * @throws {string} Throws an error if the XFL float number is negative. @@ -25,7 +24,6 @@ class XflHelpers { /** * Retrieves the mantissa of the XFL float number. - * * @param {bigint} xfl - The XFL float number. * @returns {bigint} The mantissa of the XFL float number. * @throws {string} Throws an error if the XFL float number is negative. @@ -40,7 +38,6 @@ class XflHelpers { /** * Checks if the XFL float number is negative. - * * @param {bigint} xfl - The XFL float number. * @returns {boolean} `true` if the XFL float number is negative, otherwise `false`. * @throws {string} Throws an error if the XFL float number is negative. @@ -55,7 +52,6 @@ class XflHelpers { /** * Converts an XFL float number to its string representation. - * * @param {bigint} xfl - The XFL float number. * @returns {string} The string representation of the XFL float number. * @throws {string} Throws an error if the XFL float number is negative. @@ -88,7 +84,6 @@ class XflHelpers { /** * Converts a string representation of a float number to an XFL float number. - * * @param {string} floatStr - The string representation of the float number. * @returns {bigint} The XFL float number. */ From 0aa9eae23149eec23ac8b1c235896f3cbf33cadb Mon Sep 17 00:00:00 2001 From: Dulana Peiris Date: Thu, 26 Sep 2024 11:15:04 +0530 Subject: [PATCH 3/4] code review changes --- docs/evernode-js-api.md | 12 ++++++------ package.json | 2 +- src/clients/base-evernode-client.js | 2 +- src/xrpl-api.js | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/evernode-js-api.md b/docs/evernode-js-api.md index 7b76ae9..ec3ac95 100644 --- a/docs/evernode-js-api.md +++ b/docs/evernode-js-api.md @@ -152,7 +152,7 @@ Detach the listener event. Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. **Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) -**Returns**: Returns `true` if the connection is successful. +**Returns**: Boolean value `true` if the connection is successful. ### baseEvernodeClient.disconnect() @@ -583,7 +583,7 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [FoundationClient](#FoundationClient) **Overrides**: [connect](#BaseEvernodeClient+connect) -**Returns**: Returns `true` if the connection is successful. +**Returns**: Boolean value `true` if the connection is successful. ### foundationClient.disconnect() @@ -907,7 +907,7 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [HeartbeatClient](#HeartbeatClient) **Overrides**: [connect](#BaseEvernodeClient+connect) -**Returns**: Returns `true` if the connection is successful. +**Returns**: Boolean value `true` if the connection is successful. ### heartbeatClient.disconnect() @@ -1262,7 +1262,7 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [RegistryClient](#RegistryClient) **Overrides**: [connect](#BaseEvernodeClient+connect) -**Returns**: Returns `true` if the connection is successful. +**Returns**: Boolean value `true` if the connection is successful. ### registryClient.disconnect() @@ -2041,7 +2041,7 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [HostClient](#HostClient) **Overrides**: [connect](#BaseEvernodeClient+connect) -**Returns**: Returns `true` if the connection is successful. +**Returns**: Boolean value `true` if the connection is successful. ### hostClient.disconnect() @@ -2540,7 +2540,7 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [TenantClient](#TenantClient) **Overrides**: [connect](#BaseEvernodeClient+connect) -**Returns**: Returns `true` if the connection is successful. +**Returns**: Boolean value `true` if the connection is successful. ### tenantClient.disconnect() diff --git a/package.json b/package.json index 9535a04..352f362 100644 --- a/package.json +++ b/package.json @@ -26,6 +26,6 @@ }, "devDependencies": { "eslint": "8.3.0", - "jsdoc-to-markdown": "^9.0.1" + "jsdoc-to-markdown": "9.0.1" } } \ No newline at end of file diff --git a/src/clients/base-evernode-client.js b/src/clients/base-evernode-client.js index eef922f..e68e49b 100644 --- a/src/clients/base-evernode-client.js +++ b/src/clients/base-evernode-client.js @@ -104,7 +104,7 @@ class BaseEvernodeClient { /** * Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. - * @returns Returns `true` if the connection is successful. + * @returns Boolean value `true` if the connection is successful. */ async connect(options = {}) { if (this.connected) diff --git a/src/xrpl-api.js b/src/xrpl-api.js index 6c5e1b7..77f3165 100644 --- a/src/xrpl-api.js +++ b/src/xrpl-api.js @@ -753,7 +753,7 @@ class XrplApi { * @param {string} txHash - Transaction Hash * @param {number} lastLedger - Last ledger sequence of the transaction. * @param {object} submissionResult - Result of the submission. - * @returns Returns the applied transaction object. + * @returns The applied transaction object. */ async #waitForFinalTransactionOutcome(txHash, lastLedger, submissionResult) { if (lastLedger == null) From aee715db67f520219445c20842e6949ddf8b7da8 Mon Sep 17 00:00:00 2001 From: Dulana Peiris Date: Fri, 27 Sep 2024 14:41:11 +0530 Subject: [PATCH 4/4] minor bug fix --- docs/evernode-js-api.md | 328 ++++++++++++++++++++++++++++++++++++++++ docs/filelist | 2 +- 2 files changed, 329 insertions(+), 1 deletion(-) diff --git a/docs/evernode-js-api.md b/docs/evernode-js-api.md index ec3ac95..b92bdf3 100644 --- a/docs/evernode-js-api.md +++ b/docs/evernode-js-api.md @@ -9,6 +9,10 @@

FoundationClient class to manage and interact with foundation operations. It extends the BaseEvernodeClient.

+
GovernorClient ⇐ BaseEvernodeClient
+

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.

+
HeartbeatClient ⇐ BaseEvernodeClient

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.

@@ -824,6 +828,330 @@ Get reputation info of given host. | --- | --- | --- | | hostsAddress | string | Host address. | + + +## GovernorClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) +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. + +**Kind**: global class +**Extends**: [BaseEvernodeClient](#BaseEvernodeClient) + +* [GovernorClient](#GovernorClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [.on(event, handler)](#BaseEvernodeClient+on) + * [.once(event, handler)](#BaseEvernodeClient+once) + * [.off(event, handler)](#BaseEvernodeClient+off) + * [.connect()](#BaseEvernodeClient+connect) ⇒ + * [.disconnect()](#BaseEvernodeClient+disconnect) + * [.subscribe()](#BaseEvernodeClient+subscribe) + * [.unsubscribe()](#BaseEvernodeClient+unsubscribe) + * [.getEVRBalance()](#BaseEvernodeClient+getEVRBalance) ⇒ + * [.getHookStates()](#BaseEvernodeClient+getHookStates) ⇒ + * [.getMoment(index)](#BaseEvernodeClient+getMoment) ⇒ + * [.getMomentStartIndex(index)](#BaseEvernodeClient+getMomentStartIndex) ⇒ + * [.refreshConfig()](#BaseEvernodeClient+refreshConfig) + * [.extractEvernodeEvent(tx)](#BaseEvernodeClient+extractEvernodeEvent) ⇒ + * [.getHostInfo(hostAddress)](#BaseEvernodeClient+getHostInfo) ⇒ + * [.getAllHostsFromLedger()](#BaseEvernodeClient+getAllHostsFromLedger) ⇒ + * [.getAllCandidatesFromLedger()](#BaseEvernodeClient+getAllCandidatesFromLedger) ⇒ + * [.pruneDeadHost(hostAddress)](#BaseEvernodeClient+pruneDeadHost) + * [.getCandidateByOwner(ownerAddress)](#BaseEvernodeClient+getCandidateByOwner) ⇒ + * [.getDudHostCandidatesByOwner(ownerAddress)](#BaseEvernodeClient+getDudHostCandidatesByOwner) ⇒ + * [.getCandidateById(candidateId)](#BaseEvernodeClient+getCandidateById) ⇒ + * [.getDudHostVoteInfo(hostAddress)](#BaseEvernodeClient+getDudHostVoteInfo) ⇒ + * [.getPilotedModeVoteInfo()](#BaseEvernodeClient+getPilotedModeVoteInfo) ⇒ + * [.getReputationAddressByOrderedId(orderedId, moment)](#BaseEvernodeClient+getReputationAddressByOrderedId) ⇒ + * [.getReputationOrderByAddress(hostAddress, moment)](#BaseEvernodeClient+getReputationOrderByAddress) ⇒ + * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ + * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + + +### governorClient.on(event, handler) +Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [on](#BaseEvernodeClient+on) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| handler | function | The callback function to handle the event. The function takes the event object as a parameter. | + + + +### governorClient.once(event, handler) +Listens to the subscribed events. This will listen only once and detach the handler. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [once](#BaseEvernodeClient+once) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | Event name. | +| handler | function | Callback function to handle the event. | + + + +### governorClient.off(event, handler) +Detach the listener event. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [off](#BaseEvernodeClient+off) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | Event name. | +| handler | function | | (optional) Can be sent if a specific handler need to be detached. All the handlers will be detached if not specified. | + + + +### governorClient.connect() ⇒ +Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [connect](#BaseEvernodeClient+connect) +**Returns**: Boolean value `true` if the connection is successful. + + +### governorClient.disconnect() +Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [disconnect](#BaseEvernodeClient+disconnect) + + +### governorClient.subscribe() +Subscribes to the client events. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [subscribe](#BaseEvernodeClient+subscribe) + + +### governorClient.unsubscribe() +Unsubscribes from the client events. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [unsubscribe](#BaseEvernodeClient+unsubscribe) + + +### governorClient.getEVRBalance() ⇒ +Get the EVR balance in the account. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getEVRBalance](#BaseEvernodeClient+getEVRBalance) +**Returns**: The available EVR amount as a string. + + +### governorClient.getHookStates() ⇒ +Get all XRPL hook states in the registry account. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getHookStates](#BaseEvernodeClient+getHookStates) +**Returns**: The list of hook states, including Evernode configuration and hosts. + + +### governorClient.getMoment(index) ⇒ +Get the moment from the given index (timestamp). + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getMoment](#BaseEvernodeClient+getMoment) +**Returns**: The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment value. | + + + +### governorClient.getMomentStartIndex(index) ⇒ +Get start index (timestamp) of the moment. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getMomentStartIndex](#BaseEvernodeClient+getMomentStartIndex) +**Returns**: The index (timestamp) of the moment as a 'number'. Returns the current moment's start index (timestamp) if ledger index parameter is not given. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| index | number | | [Optional] Index (timestamp) to get the moment start index. | + + + +### governorClient.refreshConfig() +Loads the configs from XRPL hook and updates the in-memory config. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [refreshConfig](#BaseEvernodeClient+refreshConfig) + + +### governorClient.extractEvernodeEvent(tx) ⇒ +Extracts the transaction info from a given transaction. +Note: You need to deserialize HookParameters before passing the transaction to this function. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [extractEvernodeEvent](#BaseEvernodeClient+extractEvernodeEvent) +**Returns**: The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. + +| Param | Type | Description | +| --- | --- | --- | +| tx | object | The transaction object to be deserialized and extracted. | + + + +### governorClient.getHostInfo(hostAddress) ⇒ +Get the registered host information. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getHostInfo](#BaseEvernodeClient+getHostInfo) +**Returns**: The registered host information object. Returns null if not registered. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the host. | + + + +### governorClient.getAllHostsFromLedger() ⇒ +Get the hosts registered in Evernode. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getAllHostsFromLedger](#BaseEvernodeClient+getAllHostsFromLedger) +**Returns**: The list of hosts. + + +### governorClient.getAllCandidatesFromLedger() ⇒ +Get the governor in Evernode. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getAllCandidatesFromLedger](#BaseEvernodeClient+getAllCandidatesFromLedger) +**Returns**: The list of candidates. + + +### governorClient.pruneDeadHost(hostAddress) +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. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [pruneDeadHost](#BaseEvernodeClient+pruneDeadHost) + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | XRPL address of the host to be pruned. | + + + +### governorClient.getCandidateByOwner(ownerAddress) ⇒ +Get proposed new hook candidate info. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getCandidateByOwner](#BaseEvernodeClient+getCandidateByOwner) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | [Optional] Address of the owner. | + + + +### governorClient.getDudHostCandidatesByOwner(ownerAddress) ⇒ +Get proposed dud host candidates. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getDudHostCandidatesByOwner](#BaseEvernodeClient+getDudHostCandidatesByOwner) +**Returns**: An array of candidate information. Returns empty array if no candidates. + +| Param | Type | Description | +| --- | --- | --- | +| ownerAddress | string | | Address of the owner | + + + +### governorClient.getCandidateById(candidateId) ⇒ +Get candidate info. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getCandidateById](#BaseEvernodeClient+getCandidateById) +**Returns**: The candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| candidateId | string | Id of the candidate. | + + + +### governorClient.getDudHostVoteInfo(hostAddress) ⇒ +Get reported dud host info. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getDudHostVoteInfo](#BaseEvernodeClient+getDudHostVoteInfo) +**Returns**: The dud host candidate information. Returns null if no candidate. + +| Param | Type | Description | +| --- | --- | --- | +| hostAddress | string | [Optional] Address of the dud host. | + + + +### governorClient.getPilotedModeVoteInfo() ⇒ +Get piloted mode vote info. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getPilotedModeVoteInfo](#BaseEvernodeClient+getPilotedModeVoteInfo) +**Returns**: The piloted mode candidate information. Returns null if no candidate. + + +### governorClient.getReputationAddressByOrderedId(orderedId, moment) ⇒ +Get reputation order info of given orderedId. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getReputationAddressByOrderedId](#BaseEvernodeClient+getReputationAddressByOrderedId) +**Returns**: Reputation address info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| orderedId | number | | Order id of the host. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### governorClient.getReputationOrderByAddress(hostAddress, moment) ⇒ +Get reputation order info of given host. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getReputationOrderByAddress](#BaseEvernodeClient+getReputationOrderByAddress) +**Returns**: Reputation order info object. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | (optional) Host address. | +| moment | number | | (optional) Moment to get reputation info for. | + + + +### governorClient.getReputationContractInfoByAddress(hostsAddress, moment) ⇒ +Get reputation contract info of given host. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getReputationContractInfoByAddress](#BaseEvernodeClient+getReputationContractInfoByAddress) +**Returns**: Reputation contract info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | +| moment | number | (optional) Moment to get reputation contract info for. | + + + +### governorClient.getReputationInfoByAddress(hostsAddress) ⇒ +Get reputation info of given host. + +**Kind**: instance method of [GovernorClient](#GovernorClient) +**Overrides**: [getReputationInfoByAddress](#BaseEvernodeClient+getReputationInfoByAddress) +**Returns**: Reputation info object. + +| Param | Type | Description | +| --- | --- | --- | +| hostsAddress | string | Host address. | + ## HeartbeatClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) diff --git a/docs/filelist b/docs/filelist index 971cde5..6ff1744 100644 --- a/docs/filelist +++ b/docs/filelist @@ -1,6 +1,6 @@ src/defaults.js src/clients/hook-clients/registry-client.js -rc/clients/hook-clients/governor-client.js +src/clients/hook-clients/governor-client.js src/clients/hook-clients/heartbeat-client.js src/clients/hook-clients/hook-client-factory.js src/clients/base-evernode-client.js